@gotgenes/pi-subagents 11.2.0 → 11.4.0

package/src/lifecycle/agent.ts

@@ -11,7 +11,10 @@
  * Behavior (abort, steer buffering, worktree setup) lives on the agent
  * rather than on AgentManager — each agent manages its own lifecycle concerns.
  *
- * Phase-specific collaborators (execution, worktreeState, notification) are attached
+ * Worktree isolation is delegated to an optional WorktreeIsolation collaborator
+ * (set at construction when isolation is requested); its presence IS the mode.
+ *
+ * Phase-specific collaborators (execution, notification) are attached
  * after construction as lifecycle information becomes available.
  */
 
@@ -23,12 +26,11 @@ import type { ExecutionState } from "#src/lifecycle/execution-state";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
-import type { WorktreeManager } from "#src/lifecycle/worktree";
-import { WorktreeState } from "#src/lifecycle/worktree-state";
+import type { WorktreeIsolation } from "#src/lifecycle/worktree-isolation";
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeAgentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
-import type { AgentInvocation, CompactionInfo, IsolationMode, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
+import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Per-agent lifecycle observer — created by AgentManager for each spawn. */
 export interface AgentLifecycleObserver {
@@ -67,7 +69,7 @@ export interface AgentInit {
 
 	// Shared deps (required for run(), optional for tests)
 	runner?: AgentRunner;
-	worktrees?: WorktreeManager;
+	worktree?: WorktreeIsolation;
 	observer?: AgentLifecycleObserver;
 	getRunConfig?: () => RunConfig;
 
@@ -78,7 +80,6 @@ export interface AgentInit {
 	maxTurns?: number;
 	isolated?: boolean;
 	thinkingLevel?: ThinkingLevel;
-	isolation?: IsolationMode;
 	parentSession?: ParentSessionInfo;
 	isBackground?: boolean;
 	signal?: AbortSignal;
@@ -124,7 +125,8 @@ export class Agent {
 
 	// Shared deps — optional (required for run())
 	private readonly _runner?: AgentRunner;
-	private readonly _worktrees?: WorktreeManager;
+	/** Worktree isolation collaborator — present only when isolation: "worktree". */
+	readonly worktree?: WorktreeIsolation;
 	readonly observer?: AgentLifecycleObserver;
 	private readonly _getRunConfig?: () => RunConfig;
 
@@ -135,37 +137,13 @@ export class Agent {
 	private readonly _maxTurns?: number;
 	private readonly _isolated?: boolean;
 	private readonly _thinkingLevel?: ThinkingLevel;
-	private readonly _isolation?: IsolationMode;
 	private readonly _parentSession?: ParentSessionInfo;
 	private readonly _signal?: AbortSignal;
 
 	// Phase-specific collaborators — each born complete when their info becomes available
 	execution?: ExecutionState;
-	worktreeState?: WorktreeState;
 	notification?: NotificationState;
 
-	/**
-	 * Create a git worktree for isolated execution, set worktreeState, and return the worktree path.
-	 * Returns undefined if isolation is not "worktree".
-	 * Throws if worktree creation fails (strict isolation).
-	 * Uses this._worktrees and this._isolation (set at construction).
-	 */
-	setupWorktree(): string | undefined {
-		if (this._isolation !== "worktree") return undefined;
-		if (!this._worktrees) {
-			throw new Error("Agent not configured for worktree isolation — missing worktrees dependency");
-		}
-		const wt = this._worktrees.create(this.id);
-		if (!wt) {
-			throw new Error(
-				'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
-				'Initialize git and commit at least once, or omit `isolation`.',
-			);
-		}
-		this.worktreeState = new WorktreeState(wt);
-		return wt.path;
-	}
-
 	// Steer buffer — messages queued before the session is ready
 	private _pendingSteers: string[] = [];
 	/** Number of steer messages waiting to be delivered. */
@@ -205,7 +183,7 @@ export class Agent {
 
 		// Shared deps
 		this._runner = init.runner;
-		this._worktrees = init.worktrees;
+		this.worktree = init.worktree;
 		this.observer = init.observer;
 		this._getRunConfig = init.getRunConfig;
 
@@ -216,7 +194,6 @@ export class Agent {
 		this._maxTurns = init.maxTurns;
 		this._isolated = init.isolated;
 		this._thinkingLevel = init.thinkingLevel;
-		this._isolation = init.isolation;
 		this._parentSession = init.parentSession;
 		this._signal = init.signal;
 
@@ -247,7 +224,7 @@ export class Agent {
 		this.wireSignal(this._signal, () => this.abort());
 
 		try {
-			this.setupWorktree();
+			this.worktree?.setup();
 		} catch (err) {
 			this.markError(err);
 			this.releaseListeners();
@@ -259,7 +236,7 @@ export class Agent {
 		try {
 			const result = await this._runner.run(this._snapshot, this.type, this._prompt, {
 				context: {
-					cwd: this.worktreeState?.path,
+					cwd: this.worktree?.path,
 					parentSession: this._parentSession,
 				},
 				model: this._model,
@@ -465,11 +442,9 @@ export class Agent {
 		this.releaseListeners();
 
 		let finalResult = result.responseText;
-		if (this.worktreeState && this._worktrees) {
-			const wtResult = this.worktreeState.performCleanup(this._worktrees, this.description);
-			if (wtResult.hasChanges && wtResult.branch) {
-				finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
-			}
+		const wtResult = this.worktree?.cleanup(this.description);
+		if (wtResult?.hasChanges && wtResult.branch) {
+			finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
 		}
 
 		if (result.aborted) this.markAborted(finalResult);
@@ -489,11 +464,9 @@ export class Agent {
 		this.markError(err);
 		this.releaseListeners();
 
-		if (this.worktreeState && this._worktrees) {
-			try {
-				this.worktreeState.performCleanup(this._worktrees, this.description);
-			} catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
-		}
+		try {
+			this.worktree?.cleanup(this.description);
+		} catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
 
 		this.observer?.onRunFinished?.(this);
 	}

package/src/lifecycle/child-lifecycle.ts

@@ -0,0 +1,89 @@
+/**
+ * child-lifecycle.ts — Child-execution lifecycle event contract and publisher.
+ *
+ * The core publishes its child-execution lifecycle as ordered events on the Pi
+ * event bus; reactive consumers (permissions, telemetry, UI) subscribe rather
+ * than the core reaching out to them (ADR 0002). This module owns the channel
+ * names, payload shapes, and the publisher that emits them.
+ *
+ * The publisher takes an injected `emit` callback so this module stays free of
+ * Pi SDK imports — `index.ts` wires it to `pi.events.emit`.
+ */
+
+/** Emitted at the start of a child run, before the session is created. */
+export const SUBAGENT_CHILD_SPAWNING = "subagents:child:spawning";
+
+/**
+ * Emitted after the child session is created, immediately before
+ * `bindExtensions()`. Carries the child identity consumers need to register
+ * the session. Subscribers must register synchronously so the entry lands
+ * before binding proceeds (see ADR 0002 / the event-bus synchronous-dispatch
+ * guarantee).
+ */
+export const SUBAGENT_CHILD_SESSION_CREATED = "subagents:child:session-created";
+
+/** Emitted after the child's prompt resolves (normal, steered, or aborted). */
+export const SUBAGENT_CHILD_COMPLETED = "subagents:child:completed";
+
+/** Emitted in the run's `finally` — always fires, on success and error. */
+export const SUBAGENT_CHILD_DISPOSED = "subagents:child:disposed";
+
+/** Payload for `subagents:child:spawning`. */
+export interface ChildSpawningEvent {
+  agentName: string;
+  parentSessionId?: string;
+}
+
+/** Payload for `subagents:child:session-created`. */
+export interface ChildSessionCreatedEvent {
+  /** Child session directory — the registry key. */
+  sessionDir: string;
+  agentName: string;
+  parentSessionId?: string;
+}
+
+/** Payload for `subagents:child:completed`. */
+export interface ChildCompletedEvent {
+  sessionDir: string;
+  agentName: string;
+  /** True if the run was hard-aborted (max turns + grace exceeded). */
+  aborted: boolean;
+  /** True if the run was steered to wrap up (soft turn limit) but finished. */
+  steered: boolean;
+}
+
+/** Payload for `subagents:child:disposed`. */
+export interface ChildDisposedEvent {
+  sessionDir: string;
+}
+
+/** Narrow emit seam — injected, never imports the Pi SDK. */
+export type LifecycleEmit = (channel: string, data: unknown) => void;
+
+/** Publishes the child-execution lifecycle on the event bus. */
+export interface ChildLifecyclePublisher {
+  spawning(event: ChildSpawningEvent): void;
+  sessionCreated(event: ChildSessionCreatedEvent): void;
+  completed(event: ChildCompletedEvent): void;
+  disposed(event: ChildDisposedEvent): void;
+}
+
+/** Build a publisher backed by an injected `emit` callback. */
+export function createChildLifecyclePublisher(
+  emit: LifecycleEmit,
+): ChildLifecyclePublisher {
+  return {
+    spawning(event) {
+      emit(SUBAGENT_CHILD_SPAWNING, event);
+    },
+    sessionCreated(event) {
+      emit(SUBAGENT_CHILD_SESSION_CREATED, event);
+    },
+    completed(event) {
+      emit(SUBAGENT_CHILD_COMPLETED, event);
+    },
+    disposed(event) {
+      emit(SUBAGENT_CHILD_DISPOSED, event);
+    },
+  };
+}

package/src/lifecycle/worktree-isolation.ts

@@ -0,0 +1,59 @@
+/**
+ * worktree-isolation.ts — WorktreeIsolation: collaborator that owns the
+ * git-worktree lifecycle for an isolated agent.
+ *
+ * Constructed by AgentManager only when isolation === "worktree", bound to a
+ * WorktreeManager and the agent id. Agent tells it `setup()` and
+ * `cleanup(description)` instead of managing worktree internals itself.
+ *
+ * The presence/absence of this collaborator IS the isolation mode: Agent calls
+ * `this.worktree?.setup()` rather than checking an isolation string.
+ */
+
+import type { WorktreeCleanupResult, WorktreeInfo, WorktreeManager } from "#src/lifecycle/worktree";
+
+export class WorktreeIsolation {
+	private _info?: WorktreeInfo;
+	private _cleanupResult?: WorktreeCleanupResult;
+
+	constructor(
+		private readonly worktrees: WorktreeManager,
+		private readonly agentId: string,
+	) {}
+
+	/** Absolute worktree path — undefined before setup(). */
+	get path(): string | undefined {
+		return this._info?.path;
+	}
+
+	/** Cleanup outcome — undefined until cleanup() runs. */
+	get cleanupResult(): WorktreeCleanupResult | undefined {
+		return this._cleanupResult;
+	}
+
+	/**
+	 * Create the git worktree and store its info.
+	 * Throws on failure (strict isolation — no silent fallback).
+	 */
+	setup(): void {
+		const wt = this.worktrees.create(this.agentId);
+		if (!wt) {
+			throw new Error(
+				'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
+					"Initialize git and commit at least once, or omit `isolation`.",
+			);
+		}
+		this._info = wt;
+	}
+
+	/**
+	 * Perform worktree cleanup and record the result.
+	 * No-op returning { hasChanges: false } if setup never ran.
+	 */
+	cleanup(description: string): WorktreeCleanupResult {
+		if (!this._info) return { hasChanges: false };
+		const result = this.worktrees.cleanup(this._info, description);
+		this._cleanupResult = result;
+		return result;
+	}
+}

package/src/service/service-adapter.ts

@@ -128,7 +128,7 @@ export function toSubagentRecord(record: Agent): SubagentRecord {
   if (record.result !== undefined) out.result = record.result;
   if (record.error !== undefined) out.error = record.error;
   if (record.completedAt !== undefined) out.completedAt = record.completedAt;
-  const worktreeResult = record.worktreeState?.cleanupResult;
+  const worktreeResult = record.worktree?.cleanupResult;
   if (worktreeResult !== undefined) out.worktreeResult = worktreeResult;
 
   return out;

package/src/lifecycle/permission-bridge.ts

@@ -1,63 +0,0 @@
-/**
- * permission-bridge.ts — Cross-extension bridge to @gotgenes/pi-permission-system.
- *
- * pi-subagents does not import pi-permission-system directly. Instead it
- * accesses the published PermissionsService via a process-global Symbol.for()
- * key, the same mechanism pi-permission-system uses to publish itself.
- *
- * When pi-permission-system is not installed, getPermissionsService() returns
- * undefined and all registration calls are silent no-ops.
- */
-
-/**
- * The two PermissionsService methods pi-subagents needs.
- *
- * Follows ISP — does not expose the full PermissionsService surface
- * (checkPermission, getToolPermission, etc.) to avoid coupling.
- */
-interface PermissionsServiceConsumer {
-	registerSubagentSession(
-		sessionKey: string,
-		info: { parentSessionId?: string; agentName: string },
-	): void;
-	unregisterSubagentSession(sessionKey: string): void;
-}
-
-const PERMISSION_SERVICE_KEY = Symbol.for(
-	"@gotgenes/pi-permission-system:service",
-);
-
-function getPermissionsService(): PermissionsServiceConsumer | undefined {
-	return (globalThis as Record<symbol, unknown>)[
-		PERMISSION_SERVICE_KEY
-	] as PermissionsServiceConsumer | undefined;
-}
-
-/**
- * Register a child session with pi-permission-system's SubagentSessionRegistry.
- *
- * Must be called after deriving sessionDir but before session.bindExtensions()
- * so isSubagentExecutionContext() hits the registry on the first check during
- * child extension initialization.
- *
- * @param sessionKey - The session directory path (unique per session).
- * @param info       - Agent name and optional parent session ID for forwarding.
- */
-export function registerChildSession(
-	sessionKey: string,
-	info: { parentSessionId?: string; agentName: string },
-): void {
-	getPermissionsService()?.registerSubagentSession(sessionKey, info);
-}
-
-/**
- * Unregister a child session from pi-permission-system's SubagentSessionRegistry.
- *
- * Must be called in a finally block so cleanup happens on both success and
- * error paths.
- *
- * @param sessionKey - The session directory path used during registration.
- */
-export function unregisterChildSession(sessionKey: string): void {
-	getPermissionsService()?.unregisterSubagentSession(sessionKey);
-}

package/src/lifecycle/worktree-state.ts

@@ -1,45 +0,0 @@
-/**
- * worktree-state.ts — WorktreeState: lifecycle-phase object for worktree-isolated agents.
- *
- * Constructed once when the worktree is set up (before the run begins).
- * Only exists for agents with isolation: "worktree".
- * cleanupResult is recorded once at completion or error — it is not set at construction.
- */
-
-import type { WorktreeCleanupResult, WorktreeInfo, WorktreeManager } from "#src/lifecycle/worktree";
-
-export type { WorktreeCleanupResult, WorktreeInfo };
-
-export class WorktreeState {
-	/** Absolute path to the worktree directory. */
-	readonly path: string;
-	/** Branch name created for this worktree. */
-	readonly branch: string;
-
-	private _cleanupResult?: WorktreeCleanupResult;
-
-	constructor(info: WorktreeInfo) {
-		this.path = info.path;
-		this.branch = info.branch;
-	}
-
-	/** Result of the worktree cleanup — undefined until recordCleanup is called. */
-	get cleanupResult(): WorktreeCleanupResult | undefined {
-		return this._cleanupResult;
-	}
-
-	/** Record the cleanup result. Called once on agent completion or error. */
-	recordCleanup(result: WorktreeCleanupResult): void {
-		this._cleanupResult = result;
-	}
-
-	/**
-	 * Perform worktree cleanup and record the result.
-	 * Tell-Don't-Ask: callers no longer need to orchestrate cleanup + recordCleanup separately.
-	 */
-	performCleanup(worktrees: WorktreeManager, description: string): WorktreeCleanupResult {
-		const result = worktrees.cleanup(this, description);
-		this._cleanupResult = result;
-		return result;
-	}
-}