pi-crew 0.9.41 → 0.9.44

package/src/extension/registration/command-registration.ts

@@ -0,0 +1,57 @@
+/**
+ * Command registration installer for pi-crew.
+ *
+ * Single entry point that wires every `pi.registerCommand(...)` call
+ * site in the extension. Today that means one heavy call:
+ *   • `registerTeamCommands` — registers every `/crew-*`, `/team-*`,
+ *     `/teams`, and friends. The full set lives in
+ *     `registration/commands.ts` (already extracted); this file is
+ *     the orchestrator-level wrapper that calls it with the right deps.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import { updatePiCrewPowerbar } from "../../ui/powerbar-publisher.ts";
+import { updateCrewWidget } from "../../ui/widget/index.ts";
+import { registerTeamCommands } from "./commands.ts";
+import type { RegistrationContext } from "./registration-types.ts";
+
+/**
+ * Register all pi-crew slash commands on the ExtensionAPI.
+ *
+ * The dismiss-notifications callback (used by commands like
+ * `/crew-notifications dismiss`) needs to refresh both the widget and
+ * the powerbar with the new count, so we read `currentCtx` + `widgetState`
+ * lazily off the context.
+ */
+export function registerPiCommands(pi: ExtensionAPI, ctx: RegistrationContext): void {
+	registerTeamCommands(pi, {
+		startForegroundRun: ctx.startForegroundRun,
+		abortForegroundRun: ctx.abortForegroundRun,
+		openLiveSidebar: ctx.openLiveSidebar,
+		getManifestCache: ctx.getManifestCache,
+		getRunSnapshotCache: ctx.getRunSnapshotCache,
+		getMetricRegistry: () => ctx.observabilityState.metricRegistry,
+		dismissNotifications: () => {
+			ctx.widgetState.notificationCount = 0;
+			if (ctx.currentCtx) {
+				const uiConfig = loadConfig(ctx.currentCtx.cwd).config.ui;
+				updateCrewWidget(
+					ctx.currentCtx,
+					ctx.widgetState,
+					uiConfig,
+					ctx.getManifestCache(ctx.currentCtx.cwd),
+					ctx.getRunSnapshotCache(ctx.currentCtx.cwd),
+				);
+				updatePiCrewPowerbar(
+					pi.events,
+					ctx.currentCtx.cwd,
+					uiConfig,
+					ctx.getManifestCache(ctx.currentCtx.cwd),
+					ctx.getRunSnapshotCache(ctx.currentCtx.cwd),
+					ctx.currentCtx,
+					0,
+				);
+			}
+		},
+	});
+}

package/src/extension/registration/commands.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "../../config/config.ts";
+import { atomicWriteFile } from "../../state/atomic-write.ts";
 // Lazy-loaded: team-tool.ts pulls in entire runtime chain (1.4s+).
 import type { handleTeamTool as HandleTeamToolFn } from "../team-tool.ts";
 
@@ -1113,7 +1114,11 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 			const useProject = tokens.includes("--project");
 			const varEntries = tokens
 				.filter((t) => t.startsWith("--var=") || t.startsWith("--var "))
-				.map((t) => t.replace(/^--var(?:\s+|=)/, "").split("=", 2) as [string, string]);
+				.map((t): [string, string] => {
+					const s = t.replace(/^--var(?:\s+|=)/, "");
+					const idx = s.indexOf("=");
+					return idx === -1 ? [s, ""] : [s.slice(0, idx), s.slice(idx + 1)];
+				});
 			const templateId = tokens.find((t) => !t.startsWith("--") && !t.includes("="));
 			if (!templateId) {
 				await notifyCommandResult(
@@ -1171,7 +1176,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 			const skillPath = path.join(skillDir, "SKILL.md");
 			try {
 				fs.mkdirSync(skillDir, { recursive: true });
-				fs.writeFileSync(skillPath, instantiated.content, "utf-8");
+				atomicWriteFile(skillPath, instantiated.content);
 				await notifyCommandResult(
 					ctx,
 					`Created skill '${template.id}' at:\n${skillPath}\n\n${instantiated.content.slice(0, 200)}...`,

package/src/extension/registration/context-builder.ts

@@ -0,0 +1,131 @@
+/**
+ * RegistrationContext builder.
+ *
+ * Pure construction of the mutable state bag passed to every install*
+ * helper under `./registration/`. Kept in its own file because the
+ * initialization is verbose (every field of the orchestrator's state
+ * is initialized here) and bundling it into `register.ts` would push
+ * that file past its size budget.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import { initI18n } from "../../i18n.ts";
+import { BatchBarrier } from "../../runtime/batch-barrier.ts";
+import { createManifestCache } from "../../runtime/manifest-cache.ts";
+import { createRunSnapshotCache } from "../../ui/run-snapshot-cache.ts";
+import type { CrewWidgetState } from "../../ui/widget/index.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import type { AsyncNotifierState } from "../async-notifier.ts";
+import type { NotificationDescriptor } from "../notification-router.ts";
+import type { LifecycleState } from "./lifecycle.ts";
+import type { ObservabilityState } from "./observability.ts";
+import type { RegistrationContext } from "./registration-types.ts";
+import { sendFollowUp } from "./subagent-helpers.ts";
+import type { UiState } from "./ui.ts";
+
+/** Module-level slot for `disposeI18n` so the cleanup helpers can find it. */
+const RUNTIME_CLEANUP_STORE_KEY = Symbol("__piCrewRuntimeCleanup");
+
+/**
+ * Build the mutable RegistrationContext. All state + bound closures
+ * that the extracted modules need are hung off this object.
+ *
+ * The shape is built once with placeholder closures for fields that the
+ * install* helpers under registration/ will rebind. Two of them
+ * (`notifyOperator`, `getManifestCache`/`getRunSnapshotCache`) are
+ * constructed inline because they only depend on the ctx itself, not
+ * on later install steps.
+ */
+export function buildRegistrationContext(pi: ExtensionAPI): RegistrationContext {
+	const ctx: RegistrationContext = {
+		pi,
+		currentCtx: undefined,
+		sessionGeneration: 0,
+		cleanedUp: false,
+		rpcHandle: undefined,
+		manifestCache: createManifestCache(process.cwd()),
+		runSnapshotCache: createRunSnapshotCache(process.cwd()),
+		cacheCwd: process.cwd(),
+		getManifestCache: undefined as never,
+		getRunSnapshotCache: undefined as never,
+		widgetState: { frame: 0 } as CrewWidgetState,
+		uiState: { liveSidebarRunId: undefined, dashboardOpened: false } as UiState,
+		observabilityState: {
+			metricRegistry: undefined,
+			eventMetricSub: undefined,
+			metricSink: undefined,
+			heartbeatWatcher: undefined,
+			autoRepairTimer: undefined,
+			tempReconcileTimer: undefined,
+			otlpExporter: undefined,
+		} as ObservabilityState,
+		lifecycleState: {
+			notifierStarted: false,
+			notificationSink: undefined,
+			notificationRouter: undefined,
+			deliveryCoordinator: undefined,
+			overflowTracker: undefined,
+		} as LifecycleState,
+		notifierState: { seenFinishedRunIds: new Set() } as AsyncNotifierState,
+		foregroundControllers: new Map(),
+		foregroundTeamRunControllers: new Map(),
+		renderScheduler: undefined,
+		renderSchedulerUnsubscribers: [],
+		terminalStatus: undefined,
+		terminalStatusActive: false,
+		crewScheduler: undefined,
+		preloadTimer: undefined,
+		crewRunWatchers: undefined,
+		userCrewWatchers: undefined,
+		subagentManager: undefined as never,
+		batchBarrier: new BatchBarrier(),
+		crewAutocompleteRegistered: false,
+		autoRecoveryLast: new Map(),
+		AUTO_RECOVERY_LAST_MAX_ENTRIES: 1000,
+		disposeI18n: initI18n(pi),
+		globalStore: globalThis as Record<string | symbol, unknown>,
+		runtimeCleanupStoreKey: RUNTIME_CLEANUP_STORE_KEY,
+		captureSessionGeneration: () => ctx.sessionGeneration,
+		isOwnerSessionCurrent: (gen) => !ctx.cleanedUp && (gen === undefined || gen === ctx.sessionGeneration),
+		isContextCurrent: (c, gen) => !ctx.cleanedUp && ctx.currentCtx === c && ctx.sessionGeneration === gen,
+		telemetryEnabled: () => loadConfig(ctx.currentCtx?.cwd ?? process.cwd()).config.telemetry?.enabled !== false,
+		notifyOperator: undefined as never,
+		cleanupSessionResourcesOnly: () => {},
+		cleanupRuntime: () => {},
+		disposeRenderSchedulerSubscriptions: () => {},
+		stopSessionBoundSubagents: () => {},
+		configureNotifications: () => {},
+		configureObservability: () => {},
+		configureDeliveryCoordinator: () => {},
+		importCrashRecovery: undefined as never,
+		purgeStaleActiveRunIndexSyncIfLoaded: () => {},
+		startForegroundRun: undefined as never,
+		abortForegroundRun: () => false,
+		openLiveSidebar: () => {},
+	};
+
+	ctx.notifyOperator = (notification: NotificationDescriptor): void => {
+		try {
+			ctx.lifecycleState.notificationRouter?.enqueue(notification);
+		} catch (error) {
+			logInternalError("register.notification", error);
+			void sendFollowUp(pi, [notification.title, notification.body].filter((line): line is string => Boolean(line)).join("\n"));
+		}
+	};
+
+	ctx.getManifestCache = (cwd: string) => {
+		if (ctx.manifestCache && ctx.cacheCwd === cwd) return ctx.manifestCache;
+		if (ctx.manifestCache) ctx.manifestCache.dispose();
+		if (ctx.runSnapshotCache) ctx.runSnapshotCache.dispose?.();
+		ctx.cacheCwd = cwd;
+		ctx.manifestCache = createManifestCache(cwd);
+		ctx.runSnapshotCache = createRunSnapshotCache(cwd);
+		return ctx.manifestCache;
+	};
+	ctx.getRunSnapshotCache = (cwd: string) => {
+		if (ctx.cacheCwd !== cwd) ctx.getManifestCache(cwd);
+		return ctx.runSnapshotCache;
+	};
+
+	return ctx;
+}

package/src/extension/registration/crash-recovery-cache.ts

@@ -0,0 +1,54 @@
+/**
+ * Crash-recovery lazy import + sync purge helper.
+ *
+ * The session_start handler needs `cancelOrphanedRuns` and
+ * `purgeStaleActiveRunIndex` from runtime/crash-recovery.ts, but that
+ * module is ~14 KB and only relevant on the orphan-cleanup path.
+ *
+ * `importCrashRecovery` defers the actual `import()` until first use,
+ * caches the result on a module-level slot, and `purgeStaleActiveRunIndexSyncIfLoaded`
+ * fires the purge only if the cache has been populated (cleanup runs
+ * synchronously and may not have triggered the lazy import yet).
+ *
+ * Module-level cache is intentional: it survives across multiple
+ * `registerPiTeams` calls during dev hot-reload, so we don't reload
+ * the heavy crash-recovery module on every reload.
+ */
+import type {
+	cancelOrphanedRuns as CancelOrphanedRunsFn,
+	detectInterruptedRuns as DetectInterruptedRunsFn,
+	purgeStaleActiveRunIndex as PurgeStaleActiveRunIndexFn,
+} from "../../runtime/crash-recovery.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+
+export type CrashRecoveryCache = {
+	cancelOrphanedRuns: typeof CancelOrphanedRunsFn;
+	detectInterruptedRuns: typeof DetectInterruptedRunsFn;
+	purgeStaleActiveRunIndex: typeof PurgeStaleActiveRunIndexFn;
+};
+
+let _cachedCrashRecovery: CrashRecoveryCache | undefined;
+
+/** Lazy-import crash-recovery. Cached after first call. */
+export async function importCrashRecovery(): Promise<CrashRecoveryCache> {
+	if (!_cachedCrashRecovery) {
+		// LAZY: defer crash-recovery (~14 KB) until session_start cleanup runs.
+		const mod = await import("../../runtime/crash-recovery.ts");
+		_cachedCrashRecovery = {
+			cancelOrphanedRuns: mod.cancelOrphanedRuns,
+			detectInterruptedRuns: mod.detectInterruptedRuns,
+			purgeStaleActiveRunIndex: mod.purgeStaleActiveRunIndex,
+		};
+	}
+	return _cachedCrashRecovery;
+}
+
+/** Sync purge-if-loaded helper used by cleanup functions. */
+export function purgeStaleActiveRunIndexSyncIfLoaded(): void {
+	if (!_cachedCrashRecovery) return;
+	try {
+		_cachedCrashRecovery.purgeStaleActiveRunIndex();
+	} catch (error) {
+		logInternalError("register.cleanupRuntime.purgeStale", error);
+	}
+}

package/src/extension/registration/foreground-run-controller.ts

@@ -0,0 +1,238 @@
+/**
+ * Foreground run controller for pi-crew.
+ *
+ * Owns the three helpers consumed by the team-tool / subagent-tools /
+ * team-commands modules:
+ *   • `startForegroundRun` — spawn a foreground team run with watchdog,
+ *     abort signal, and completion-handling (status notification + widget
+ *     refresh + crew.run.* event emission).
+ *   • `abortForegroundRun` — abort a foreground team run by runId.
+ *   • `openLiveSidebar`     — open the per-run live sidebar UI overlay.
+ *
+ * These three are conceptually one unit (all manipulate the same
+ * foreground-team-run controllers + live sidebar state), so they share
+ * a single file.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import { loadRunManifestById, updateRunStatus } from "../../state/state-store.ts";
+import { setWorkingIndicator } from "../../ui/pi-ui-compat.ts";
+import { requestPowerbarUpdate } from "../../ui/powerbar-publisher.ts";
+import { updateCrewWidget } from "../../ui/widget/index.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import type { RegistrationContext } from "./registration-types.ts";
+
+/**
+ * Install the foreground-run controller helpers into the registration
+ * context. Re-call safe — each call rebinds `ctx.startForegroundRun`,
+ * `ctx.abortForegroundRun`, and `ctx.openLiveSidebar` to fresh closures
+ * (the underlying state lives on `ctx`).
+ */
+export function installForegroundRunController(pi: ExtensionAPI, ctx: RegistrationContext): void {
+	ctx.openLiveSidebar = (extCtx, runId) => {
+		void openLiveSidebarImpl(pi, ctx, extCtx, runId);
+	};
+	ctx.startForegroundRun = (extCtx, runner, runId) => startForegroundRunImpl(pi, ctx, extCtx, runner, runId);
+	ctx.abortForegroundRun = (runId) => {
+		const controller = ctx.foregroundTeamRunControllers.get(runId);
+		if (!controller) return false;
+		controller.abort();
+		return true;
+	};
+}
+
+/**
+ * Open the live sidebar for a specific run.
+ *
+ * Defers the actual install to registration/ui.ts via a lazy dynamic
+ * import — only invoked when a sidebar is actually requested, never at
+ * module load.
+ */
+async function openLiveSidebarImpl(
+	pi: ExtensionAPI,
+	ctx: RegistrationContext,
+	extensionCtx: ExtensionContext,
+	runId: string,
+): Promise<void> {
+	// LAZY: registration/ui pulls in transcript-viewer + heavy UI modules.
+	const uiModule = await import("./ui.ts");
+	await uiModule.installLiveSidebar(extensionCtx, runId, ctx.uiState, {
+		pi,
+		widgetState: ctx.widgetState,
+		getManifestCache: ctx.getManifestCache,
+		getRunSnapshotCache: ctx.getRunSnapshotCache,
+		isCleanedUp: () => ctx.cleanedUp,
+		getCurrentCtx: () => ctx.currentCtx,
+	});
+}
+
+/**
+ * Spawn a foreground team run.
+ *
+ * The runner executes on the next macrotask (`setImmediate`) so this
+ * function returns synchronously to Pi. The runner receives an AbortSignal
+ * that fires when:
+ *   • `abortForegroundRun(runId)` is called (e.g., from a tool cancel),
+ *   • `cleanupRuntime()` fires (session shutdown with reason=quit/reload).
+ *
+ * A foreground-watchdog is started per runId to surface hung runs to the
+ * assistant. The .finally block handles: abort propagation, working-message
+ * clearing, status notification, run-completed session entry, and crew.run.*
+ * event emission.
+ */
+function startForegroundRunImpl(
+	pi: ExtensionAPI,
+	ctx: RegistrationContext,
+	extensionCtx: ExtensionContext,
+	runner: (signal?: AbortSignal) => Promise<void>,
+	runId?: string,
+): void {
+	const ownerGeneration = ctx.captureSessionGeneration();
+	const controller = new AbortController();
+	const key = runId ?? Symbol();
+	ctx.foregroundTeamRunControllers.set(key, controller);
+	if (extensionCtx.hasUI) {
+		setWorkingIndicator(extensionCtx, {
+			frames: ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"],
+			intervalMs: 80,
+		});
+		extensionCtx.ui.setWorkingMessage(runId ? `pi-crew foreground run ${runId}...` : "pi-crew foreground run...");
+	}
+	if (runId) {
+		void import("../../runtime/foreground-watchdog.ts")
+			.then(({ startForegroundWatchdog }) => {
+				startForegroundWatchdog({ pi, cwd: extensionCtx.cwd, runId });
+			})
+			.catch((error) => {
+				logInternalError("register.foreground-watchdog-import", error);
+			});
+	}
+	setImmediate(() => {
+		void runner(controller.signal)
+			.catch((error) => {
+				const message = error instanceof Error ? error.message : String(error);
+				if (runId) {
+					try {
+						const loaded = loadRunManifestById(extensionCtx.cwd, runId);
+						if (
+							loaded &&
+							loaded.manifest.status !== "completed" &&
+							loaded.manifest.status !== "failed" &&
+							loaded.manifest.status !== "cancelled" &&
+							loaded.manifest.status !== "blocked"
+						)
+							updateRunStatus(loaded.manifest, "failed", message);
+					} catch (statusError) {
+						logInternalError("register.foreground-run-failure", statusError, `runId=${runId}`);
+					}
+				}
+				if (ctx.isContextCurrent(extensionCtx, ownerGeneration)) {
+					extensionCtx.ui.notify(`pi-crew foreground run failed: ${message}`, "error");
+				} else {
+					logInternalError("register.foreground-run-failure", error, `runId=${runId} context disposed`);
+				}
+			})
+			.finally(() => {
+				ctx.foregroundTeamRunControllers.delete(key);
+				if (runId) {
+					void import("../../runtime/foreground-watchdog.ts")
+						.then(({ stopWatchdog }) => {
+							stopWatchdog(runId);
+						})
+						.catch((error) => logInternalError("register.foreground-watchdog", error, `runId=${runId}`));
+				}
+				const ownerCurrent = ctx.isContextCurrent(extensionCtx, ownerGeneration);
+				if (extensionCtx.hasUI) {
+					try {
+						setWorkingIndicator(extensionCtx);
+						extensionCtx.ui.setWorkingMessage();
+					} catch {
+						/* ignore */
+					}
+				}
+				if (ownerCurrent && runId) {
+					const loaded = loadRunManifestById(extensionCtx.cwd, runId);
+					const status = loaded?.manifest.status ?? "finished";
+					const level = status === "failed" || status === "blocked" ? "error" : status === "cancelled" ? "warning" : "info";
+					extensionCtx.ui.notify(
+						`pi-crew run ${runId} ${status}. Use /team-summary ${runId} or /team-status ${runId}.`,
+						level as "info" | "warning" | "error",
+					);
+					pi.appendEntry("crew:run-completed", {
+						runId,
+						team: loaded?.manifest.team,
+						workflow: loaded?.manifest.workflow,
+						goal: loaded?.manifest.goal,
+						status,
+						taskCount: loaded?.tasks.length,
+						durationMs: loaded?.manifest.createdAt ? Date.now() - new Date(loaded.manifest.createdAt).getTime() : 0,
+						timestamp: Date.now(),
+					});
+					const eventType =
+						status === "completed"
+							? "crew.run.completed"
+							: status === "failed" || status === "blocked"
+								? "crew.run.failed"
+								: status === "cancelled"
+									? "crew.run.cancelled"
+									: undefined;
+					if (eventType) {
+						pi.events?.emit?.(eventType, {
+							runId,
+							team: loaded?.manifest.team,
+							workflow: loaded?.manifest.workflow,
+							status,
+							taskCount: loaded?.tasks.length,
+							goal: loaded?.manifest.goal,
+							durationMs: loaded?.manifest.createdAt ? Date.now() - new Date(loaded.manifest.createdAt).getTime() : 0,
+						});
+					}
+
+					// Emit per-task events so task-level metrics (crew.task.count,
+					// crew.task.duration_ms, crew.task.tokens_total) record actual values.
+					const terminalTaskStatuses = new Set(["completed", "failed", "needs_attention"]);
+					for (const task of loaded?.tasks ?? []) {
+						if (!terminalTaskStatuses.has(task.status)) continue;
+						const taskEventType =
+							task.status === "completed"
+								? "crew.task.completed"
+								: task.status === "failed"
+									? "crew.task.failed"
+									: "crew.task.needs_attention";
+						pi.events?.emit?.(taskEventType, {
+							runId,
+							team: loaded?.manifest.team,
+							workflow: loaded?.manifest.workflow,
+							taskId: task.id,
+							taskCount: loaded?.tasks.length,
+							role: task.role,
+							durationMs:
+								task.startedAt && task.finishedAt
+									? new Date(task.finishedAt).getTime() - new Date(task.startedAt).getTime()
+									: 0,
+							tokens: (task.usage?.input ?? 0) + (task.usage?.output ?? 0),
+						});
+					}
+				}
+				if (ownerCurrent && ctx.currentCtx) {
+					const config = loadConfig(ctx.currentCtx.cwd).config.ui;
+					updateCrewWidget(
+						ctx.currentCtx,
+						ctx.widgetState,
+						config,
+						ctx.getManifestCache(ctx.currentCtx.cwd),
+						ctx.getRunSnapshotCache(ctx.currentCtx.cwd),
+					);
+					requestPowerbarUpdate(
+						pi.events,
+						ctx.currentCtx.cwd,
+						config,
+						ctx.getManifestCache(ctx.currentCtx.cwd),
+						ctx.getRunSnapshotCache(ctx.currentCtx.cwd),
+						ctx.currentCtx,
+						ctx.widgetState.notificationCount ?? 0,
+					);
+				}
+			});
+	});
+}

package/src/extension/registration/hook-registration.ts

@@ -0,0 +1,119 @@
+/**
+ * Generic event-hook installer for pi-crew.
+ *
+ * Owns the non-lifecycle `pi.on(...)` subscribers:
+ *   • `tool_call`     — destructive-team-action permission gate.
+ *   • `tool_result`   — per-write validation (catches malformed config at
+ *                       write time, not at next load).
+ *   • `resources_discover` — injects pi-crew skill paths.
+ *
+ * Session-lifecycle hooks (`session_start`, `session_shutdown`,
+ * `session_before_switch`) live in `lifecycle-handlers.ts` because they
+ * are heavy and own the deferred-cleanup + scheduler + render-loop setup.
+ *
+ * Compaction-guard hooks live in `compaction-guard.ts` because they were
+ * already extracted; this file does NOT re-register them.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { asRecord, loadConfig } from "../../config/config.ts";
+import { buildValidationBlocker, extractPathFromInput, validateWrittenFile } from "../../runtime/per-write-validator.ts";
+import { resolveContainedPath } from "../../utils/safe-paths.ts";
+import { shouldBlockDestructiveTeamAction } from "../team-tool/destructive-gate.ts";
+import type { RegistrationContext } from "./registration-types.ts";
+
+/**
+ * Register all non-lifecycle event hooks on the ExtensionAPI.
+ *
+ * Safe to call once during `registerPiTeams`. Does not stack idempotency
+ * guards — these hooks are intentionally re-registered on reload (the
+ * orchestrator's `previousRuntimeCleanup` handles cleanup of derived state).
+ */
+export function installPiHooks(pi: ExtensionAPI, ctx: RegistrationContext): void {
+	installResourcesDiscoverHook(pi, ctx);
+	installToolCallHook(pi, ctx);
+	installToolResultHook(pi, ctx);
+}
+
+/**
+ * Phase 11a: Dynamic resource discovery — inject pi-crew skill paths.
+ *
+ * Older Pi versions without `resources_discover` are tolerated (try/catch
+ * around pi.on; missing support is a no-op).
+ */
+function installResourcesDiscoverHook(pi: ExtensionAPI, ctx: RegistrationContext): void {
+	try {
+		pi.on("resources_discover", () => {
+			const sessionCwd = ctx.currentCtx?.cwd ?? process.cwd();
+			const skillDir = path.resolve(sessionCwd, "skills");
+			const extSkillDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+			const paths: string[] = [];
+			if (fs.existsSync(extSkillDir)) paths.push(extSkillDir);
+			if (skillDir !== extSkillDir && fs.existsSync(skillDir)) {
+				// Validate skillDir is within sessionCwd to prevent path traversal
+				try {
+					resolveContainedPath(sessionCwd, "skills");
+					paths.push(skillDir);
+				} catch {
+					// skillDir outside sessionCwd boundary — skip
+				}
+			}
+			return paths.length > 0 ? { skillPaths: paths } : {};
+		});
+	} catch {
+		/* older Pi without resources_discover */
+	}
+}
+
+/**
+ * Phase 1.4: Permission gate for destructive team actions.
+ *
+ * AGENTS.md requires `confirm: true` for management deletes. We enforce it
+ * at the tool_call boundary so the user gets a clear error rather than
+ * executing a destructive action silently.
+ */
+function installToolCallHook(_pi: ExtensionAPI, _ctx: RegistrationContext): void {
+	_pi.on("tool_call", async (event) => {
+		if (event.toolName !== "team") return;
+		const rawInput = event.input;
+		if (!rawInput || typeof rawInput !== "object") return;
+		const input = asRecord(rawInput);
+		if (!input) return;
+		const action = typeof input.action === "string" ? input.action : undefined;
+		const reason = shouldBlockDestructiveTeamAction(action, input);
+		if (!reason) return;
+		return {
+			block: true as const,
+			reason,
+		};
+	});
+}
+
+/**
+ * T5 (v0.8.5): per-write validation. On write/edit, run a zero-cost
+ * SYNCHRONOUS validator (v1: JSON.parse) and append a 🔴 blocker to the
+ * tool result on failure — catches malformed config the moment it's
+ * written, not at the next load. Latency-safe by construction: no process
+ * spawn, one disk read ONLY for validated extensions, dedup'd by content.
+ * Toggle via runtime.reliability.perWriteValidation (default true).
+ * Process-spawning validators (.js/.sh/.py) are a future opt-in.
+ */
+function installToolResultHook(_pi: ExtensionAPI, _ctx: RegistrationContext): void {
+	_pi.on("tool_result", (event, ctx) => {
+		try {
+			if (event.toolName !== "write" && event.toolName !== "edit") return;
+			if (loadConfig(ctx.cwd).config.reliability?.perWriteValidation === false) return;
+			const filePath = extractPathFromInput(event.input);
+			if (!filePath) return;
+			const result = validateWrittenFile(filePath);
+			if (!result || result.ok) return;
+			return {
+				content: [...event.content, buildValidationBlocker(filePath, result.error ?? "validation failed")],
+			};
+		} catch {
+			// best-effort: never break a tool result
+		}
+	});
+}