pi-agents-switch 0.2.0

package/index.ts

@@ -0,0 +1,760 @@
+/**
+ * pi-agents-switch — Primary Agent Switching for Pi
+ *
+ * Inspired by OpenCode's Tab agent cycling.
+ * Each agent is defined by a single AGENTS.md with YAML frontmatter
+ * (metadata) and Markdown body (system prompt).
+ *
+ * Features:
+ *   - F9 hotkey to cycle agents (PI → custom agents and back)
+ *   - /switch command: picker UI with provider/model shown
+ *   - /switch-config: create/delete agents, set hotkey, init builder
+ *   - Status bar shows agent name + provider/model
+ *   - before_agent_start: injects agent system prompt + applies model/thinking/tools
+ *   - before_provider_request: injects temperature / topP if configured
+ *   - Fallback chain: agent AGENTS.md → project AGENTS.md → PI defaults
+ *   - Inheritance: agent tools = PI tools - excluded_tools + tools
+ *
+ * Default "PI" agent uses your existing pi config (no changes).
+ * Custom agents have isolated profile dirs under ~/.pi/agents/<name>/
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	Key,
+	type KeyId,
+	type SelectItem,
+	SelectList,
+	Text,
+} from "@earendil-works/pi-tui";
+
+import { ProfileManager, type PIState } from "./profile-manager";
+import type {
+	AgentFrontmatter,
+	AgentsConfig,
+	ResolvedAgentConfig,
+	ThinkingLevel,
+} from "./types";
+
+// ─── Constants ─────────────────────────────────────────
+
+const PI_AGENT_NAME = "PI";
+const PI_LABEL = "🤖 PI";
+const PI_DESCRIPTION =
+	"Default Pi agent — inherits your standard AGENTS.md and full config";
+
+// The default role line in Pi's system prompt — we replace this with
+// the agent's own identity when a custom agent is active.
+const DEFAULT_ROLE_LINE =
+	"You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.";
+
+interface HotkeyChoice {
+	key: KeyId;
+	label: string;
+}
+
+const HOTKEY_CHOICES: HotkeyChoice[] = [
+	{ key: Key.f9, label: "F9" },
+	{ key: Key.f8, label: "F8" },
+	{ key: Key.ctrlShift("a"), label: "Ctrl+Shift+A" },
+	{ key: Key.ctrlAlt("a"), label: "Ctrl+Alt+A" },
+];
+
+const DEFAULT_HOTKEY: KeyId = Key.f9;
+
+// Default agent shipped with the extension: a builder that
+// understands the plugin format and can create other agents.
+const DEFAULT_AGENTS: Record<string, AgentFrontmatter> = {
+	builder: {
+		name: "🔨 Builder",
+		description:
+			"Build new agents. Ask me to create an agent and I'll write the AGENTS.md.",
+	},
+};
+
+// ─── Builder Agent System Prompt ────────────────────────
+
+const BUILDER_SYSTEM_PROMPT = `# 🔨 Builder — Agent Factory
+
+You are the **Builder** agent for **pi-agents-switch**, a Pi extension that lets users switch between custom AI agents. Your job: build new agents on demand.
+
+## What is an Agent?
+
+Each agent is defined by a single file: \`~/.pi/agents/<name>/AGENTS.md\`.
+
+This file has TWO parts:
+1. **YAML frontmatter** (between \`---\` markers) — metadata
+2. **Markdown body** (after the last \`---\`) — the system prompt injected before each turn
+
+### YAML Frontmatter Reference
+
+All available fields (all optional except \`name\`):
+
+\`\`\`yaml
+---
+name: "🎯 Agent Name"          # REQUIRED — display name (emojis welcome)
+description: "What it does"     # Short description shown in the picker
+provider: anthropic             # Model provider (e.g. anthropic, openai)
+model: claude-sonnet-4-5        # Model ID
+thinkingLevel: medium           # off | minimal | low | medium | high | xhigh
+
+excluded_tools:                 # Tools to REMOVE from PI's default set
+  -what you dont want
+
+tools:                          # Tools to ADD
+  -what you want
+
+excluded_extensions:                   # Extensions to REMOVE
+  - annoying-ext
+
+extensions:                     # Extensions to ADD
+  - my-extension
+
+excluded_skills:                       # Skills to REMOVE
+  - noisy-skill
+
+skills:                         # Skills to ADD
+  - my-skill
+---
+
+# System prompt goes here
+
+You are the **Agent Name** agent.
+Your behavior instructions...
+\`\`\`
+
+### How Inheritance Works
+
+Every agent starts with what PI already has, then:
+
+1. **Remove** items in \`excluded_tools\` / \`excluded_extensions\` / \`excluded_skills\`
+2. **Add** items in \`tools\` / \`extensions\` / \`skills\`
+3. - **Order matters.** If the same item appears in both an exclude field and an add field, the later declaration wins.
+  - \`excluded_tools: [read]\` then \`tools: [read]\` → \`read\` is added.
+  - \`tools: [read]\` then \`excluded_tools: [read]\` → \`read\` is removed.
+  - \`*\` means "all" for that category.
+
+If you want to keep only a small set of tools/skills/extensions, exclude everything with \`*\` and add back what you need.
+If you want to exclude just a few items, add \`*\` to the include list and use the exclude to remove the unwanted ones.
+
+### Agent Directory Structure
+
+\`\`\`
+~/.pi/agents/<name>/
+├── AGENTS.md          ← YAML frontmatter + system prompt (THE ONLY REQUIRED FILE)
+├── extensions/        ← Agent-specific extensions (mkdir)
+├── skills/            ← Agent-specific skills (mkdir)
+└── prompts/           ← Agent-specific prompt templates (mkdir)
+\`\`\`
+
+## Workflow: How to create an agent
+
+Follow these phases in order when building an agent.
+
+### Phase 0 — Catalog environment (always first, before any questions)
+
+Inventory what's available so you can make grounded recommendations:
+
+1. **Models**: Read \`~/.pi/agent/models.json\` → record \`{provider, modelId}\` for every model
+2. **Existing agents**: \`ls ~/.pi/agents/\` (and project \`.pi/agents/\` if applicable) → avoid name collisions
+3. **Tools currently available**: list names from your system context tool definitions
+4. **Skills currently available**: check \`<available_skills>\` block in your context, or \`ls ~/.pi/agent/skills/\` and \`ls ~/.agents/skills/\`
+5. **Extensions installed**: \`ls ~/.pi/agent/npm/node_modules/\` for pi-* packages
+
+**Never** recommend models, tools, skills, or extensions the user doesn't have installed.
+
+### Phase 1 — Gather requirements (single \`ask_user_question\` call, 4-6 questions)
+
+Cover every parameter the agent needs. Skip this phase only if the user's request is already exhaustive.
+
+**Must-cover dimensions:**
+
+| # | Dimension | Determine |
+|---|---|---|
+| 1 | **Identity** | Folder name (slug), display name (emoji OK), one-line description |
+| 2 | **Role** | Concrete scope: code review? planning? debugging? research? scaffolding? deploy? combined? |
+| 3 | **Model** | Provider + model (from Phase 0 catalog); \`thinkingLevel\`: off / minimal / low / medium / high / xhigh |
+| 4 | **Tools** | Which to add/remove? Start from a preset, let user customize |
+| 5 | **Skills** | Which to add (\`skills\`) or remove (\`excluded_skills\`)? Reference Phase 0 catalog |
+| 6 | **Extensions** | Which to add (\`extensions\`) or remove (\`excluded_extensions\`)? Reference Phase 0 catalog |
+
+**Tool presets** (offer as starting points):
+
+| Preset | \`tools\` | \`excluded_tools\` | Use for |
+|---|---|---|---|
+| 🔒 Read-only | \`[read, bash, grep, find, ls, web_search, code_search, fetch_content]\` | \`[edit, write, ast_grep_replace]\` | Research, code exploration, documentation |
+| 🔍 Reviewer | Read-only + \`[lsp_diagnostics, lsp_navigation, ast_grep_search, lens_diagnostics]\` | \`[edit, write, ast_grep_replace]\` | Code review, diagnostics, static analysis |
+| 🛠️ Full-access | (inherit all PI defaults) | — | Building, refactoring, full-stack work |
+| 📦 Minimal | \`[bash, read, write]\` | everything else | Shell scripting, simple file ops |
+
+If user picks a preset, still confirm skills/extensions/model choices.
+
+### Phase 2 — Build
+
+1. **Compose YAML frontmatter** from Phase 1 decisions — every field that was explicitly chosen
+2. **Learn From Internet** use \`web_search\` to understand how others create a good agent. You can learn from "claude code" or "opencode"
+3. **Write system prompt body** (tight, ≤50 lines): clear role description, constraints, concrete do/don't examples
+4. **Write** \`~/.pi/agents/<name>/AGENTS.md\` using the \`write\` tool — frontmatter first, then the body
+
+### Phase 3 — Verify & deliver
+
+- Confirm file exists; spot-check YAML frontmatter
+- Report: display name, switch command (\`/switch <name>\`), provider/model, tool preset, skills/extensions delta
+- Offer: "Switch now with \`/switch <name>\` to test."
+`;
+
+
+// ─── PI state snapshot ─────────────────────────────────
+
+interface PIStateSnapshot {
+	model: string | undefined;
+	thinkingLevel: ThinkingLevel;
+	tools: string[];
+}
+
+// ─── Extension Entry Point ────────────────────────────
+
+export default function agentsSwitch(pi: ExtensionAPI) {
+	let cwd: string | undefined;
+	let pm: ProfileManager;
+
+	function initPM(newCwd?: string) {
+		cwd = newCwd;
+		pm = new ProfileManager(cwd);
+	}
+	initPM();
+
+	// ─── Runtime state ──────────────────────────────────
+	let currentAgent: string = PI_AGENT_NAME;
+	let currentResolved: ResolvedAgentConfig | undefined;
+	let piSnapshot: PIStateSnapshot | undefined;
+
+	// ─── Helpers ────────────────────────────────────────
+
+	function loadCurrentAgent(config: AgentsConfig): void {
+		currentAgent = pm.getActive(config);
+	}
+
+	function getAgentSystemPromptSection(): string | undefined {
+		if (currentAgent === PI_AGENT_NAME) return undefined;
+		const prompt = pm.getSystemPrompt(currentAgent, cwd);
+		if (!prompt) return undefined;
+		return `# 🎯 Agent Mode: ${currentAgent}\n\n${prompt}`;
+	}
+
+	function getStatusLabel(): string {
+		if (currentAgent === PI_AGENT_NAME) return PI_LABEL;
+		if (currentResolved) {
+			const modelInfo = currentResolved.model
+				? ` (${currentResolved.model})`
+				: "";
+			return `🎯 ${currentResolved.label}${modelInfo}`;
+		}
+		return `🎯 ${currentAgent}`;
+	}
+
+	function updateStatus(
+		ctx?:
+			| ExtensionContext
+			| { ui: { setStatus: (key: string, text: string | undefined) => void } },
+	): void {
+		if (ctx) ctx.ui.setStatus("agent-switch", getStatusLabel());
+	}
+
+	function getPIState(): PIState {
+		return {
+			tools: pi.getActiveTools(),
+			extensions: [],
+			skills: [],
+		};
+	}
+
+	// ─── State snapshot / restore ───────────────────────
+
+	function snapshotPIState(): void {
+		if (piSnapshot) return;
+		piSnapshot = {
+			model: undefined,
+			thinkingLevel: pi.getThinkingLevel() as ThinkingLevel,
+			tools: pi.getActiveTools(),
+		};
+	}
+
+	function capturePIModel(ctx?: {
+		model?: { provider: string; id: string };
+	}): void {
+		if (!piSnapshot && ctx?.model) {
+			piSnapshot = {
+				model: `${ctx.model.provider}/${ctx.model.id}`,
+				thinkingLevel: pi.getThinkingLevel() as ThinkingLevel,
+				tools: pi.getActiveTools(),
+			};
+		} else if (piSnapshot && !piSnapshot.model && ctx?.model) {
+			piSnapshot.model = `${ctx.model.provider}/${ctx.model.id}`;
+		}
+	}
+
+	async function restorePIState(ctx?: {
+		modelRegistry: { find: (provider: string, id: string) => any };
+	}): Promise<void> {
+		if (!piSnapshot) return;
+		if (piSnapshot.model && ctx) {
+			const [provider, ...idParts] = piSnapshot.model.split("/");
+			const modelId = idParts.join("/");
+			if (provider && modelId) {
+				const model = ctx.modelRegistry.find(provider, modelId);
+				if (model) await pi.setModel(model);
+			}
+		}
+		pi.setThinkingLevel(piSnapshot.thinkingLevel);
+		if (piSnapshot.tools.length > 0) pi.setActiveTools(piSnapshot.tools);
+		piSnapshot = undefined;
+	}
+
+	// ─── Apply agent settings ───────────────────────────
+
+	async function applyAgentSettings(ctx?: {
+		modelRegistry: { find: (provider: string, id: string) => any };
+		model?: { provider: string; id: string };
+	}): Promise<void> {
+		if (currentAgent === PI_AGENT_NAME) {
+			await restorePIState(ctx);
+			currentResolved = undefined;
+			return;
+		}
+
+		const resolved = pm.resolveAgent(currentAgent, getPIState(), cwd);
+		if (!resolved) {
+			currentResolved = undefined;
+			return;
+		}
+
+		resolved.systemPrompt = pm.getSystemPrompt(currentAgent, cwd) ?? "";
+		currentResolved = resolved;
+
+		capturePIModel(ctx);
+		snapshotPIState();
+
+		if (resolved.model && ctx) {
+			const [provider, ...idParts] = resolved.model.split("/");
+			const modelId = idParts.join("/");
+			if (provider && modelId) {
+				const model = ctx.modelRegistry.find(provider, modelId);
+				if (model) {
+					const ok = await pi.setModel(model);
+					if (!ok)
+						console.error(
+							`[agents-switch] Failed to set model ${resolved.model}`,
+						);
+				} else {
+					console.error(`[agents-switch] Model ${resolved.model} not found`);
+				}
+			}
+		}
+
+		if (resolved.thinkingLevel) pi.setThinkingLevel(resolved.thinkingLevel);
+
+		if (resolved.tools.length > 0) {
+			const allNames = new Set(pi.getAllTools().map((t) => t.name));
+			const valid = resolved.tools.filter((t) => allNames.has(t));
+			if (valid.length > 0) pi.setActiveTools(valid);
+		}
+	}
+
+	// ─── Agent cycling / switching ──────────────────────
+
+	async function cycleAgent(ctx?: any): Promise<void> {
+		const config = pm.loadConfig();
+		const names = [PI_AGENT_NAME, ...pm.getAgentNames()];
+		const idx = names.indexOf(currentAgent);
+		const next = names[(idx + 1) % names.length];
+		config.active = next === PI_AGENT_NAME ? PI_AGENT_NAME : next;
+		pm.saveConfig(config);
+		currentAgent = next;
+		await applyAgentSettings(ctx);
+		updateStatus(ctx);
+	}
+
+	async function switchToAgent(name: string, ctx?: any): Promise<void> {
+		const config = pm.loadConfig();
+		if (name === PI_AGENT_NAME) {
+			config.active = PI_AGENT_NAME;
+			pm.saveConfig(config);
+			currentAgent = PI_AGENT_NAME;
+			await applyAgentSettings(ctx);
+			updateStatus(ctx);
+			return;
+		}
+		if (!pm.exists(name)) {
+			ctx?.ui?.notify?.(
+				`Agent "${name}" not found. Create it with /switch-config`,
+				"error",
+			);
+			return;
+		}
+		config.active = name;
+		pm.saveConfig(config);
+		currentAgent = name;
+		await applyAgentSettings(ctx);
+		updateStatus(ctx);
+	}
+
+	// ─── SelectList helper ──────────────────────────────
+
+	/** Show a SelectList dialog and return the chosen value (or null if cancelled). */
+	async function showSelectDialog(
+		ctx: ExtensionContext,
+		title: string,
+		items: SelectItem[],
+	): Promise<string | null> {
+		return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+			const container = new Container();
+			container.addChild(
+				new DynamicBorder((s: string) => theme.fg("accent", s)),
+			);
+			container.addChild(new Text(theme.fg("accent", theme.bold(title)), 1, 0));
+
+			const list = new SelectList(items, Math.min(items.length, 12), {
+				selectedPrefix: (t) => theme.fg("accent", t),
+				selectedText: (t) => theme.fg("accent", t),
+				description: (t) => theme.fg("muted", t),
+				scrollInfo: (t) => theme.fg("dim", t),
+				noMatch: (t) => theme.fg("warning", t),
+			});
+			list.onSelect = (item) => done(item.value);
+			list.onCancel = () => done(null);
+			container.addChild(list);
+
+			container.addChild(
+				new Text(
+					theme.fg("dim", "↑↓ navigate • enter select • esc cancel"),
+					1,
+					0,
+				),
+			);
+			container.addChild(
+				new DynamicBorder((s: string) => theme.fg("accent", s)),
+			);
+
+			return {
+				render: (w) => container.render(w),
+				invalidate: () => container.invalidate(),
+				handleInput: (data) => {
+					list.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		});
+	}
+
+	// ─── Command: /switch ───────────────────────────────
+
+	pi.registerCommand("switch", {
+		description: "Switch primary agent",
+		handler: async (_args, ctx) => {
+			initPM(ctx.cwd);
+			const config = pm.loadConfig();
+			const active = pm.getActive(config);
+			const diskProfiles = pm.list();
+
+			const items: SelectItem[] = [
+				{
+					value: PI_AGENT_NAME,
+					label: active === PI_AGENT_NAME ? `${PI_LABEL} ★` : PI_LABEL,
+					description: PI_DESCRIPTION,
+				},
+			];
+
+			for (const profile of diskProfiles) {
+				const resolved = pm.resolveAgent(profile.name, getPIState(), ctx.cwd);
+				const label = resolved
+					? `${resolved.label}${active === profile.name ? " ★" : ""}`
+					: `${profile.name}${active === profile.name ? " ★" : ""}`;
+				const parts: string[] = [];
+				if (resolved?.description) parts.push(resolved.description);
+				if (resolved?.model) parts.push(resolved.model);
+				if (resolved?.thinkingLevel)
+					parts.push(`thinking:${resolved.thinkingLevel}`);
+				items.push({
+					value: profile.name,
+					label,
+					description: parts.join(" · "),
+				});
+			}
+
+			const choice = await showSelectDialog(
+				ctx,
+				`Switch agent (current: ${currentAgent})`,
+				items,
+			);
+			if (!choice) return;
+
+			await switchToAgent(choice, ctx);
+			ctx.ui.notify(
+				choice === PI_AGENT_NAME
+					? "Switched to PI (default)"
+					: `Switched to agent: ${choice}`,
+				"info",
+			);
+		},
+	});
+
+	// ─── Command: /switch-config ────────────────────────
+
+	pi.registerCommand("switch-config", {
+		description: "Configure agents (create, delete, set hotkey)",
+		handler: async (_args, ctx) => {
+			initPM(ctx.cwd);
+
+			if (!ctx.hasUI) {
+				const config = pm.loadConfig();
+				const active = pm.getActive(config);
+				const diskProfiles = pm.list();
+				const lines = diskProfiles.map((p) => {
+					const resolved = pm.resolveAgent(p.name, getPIState(), ctx.cwd);
+					const modelInfo = resolved?.model ? ` (${resolved.model})` : "";
+					const activeMarker = active === p.name ? " ★" : "";
+					return `  ${resolved?.label ?? p.name}${modelInfo}${activeMarker} — ${resolved?.description ?? ""}`;
+				});
+				pi.sendMessage({
+					customType: "agent-switch-config",
+					content: `# Agents\n\nActive: ${active}\n\n${lines.join("\n")}\n\nUse /switch to switch.`,
+					display: true,
+				});
+				return;
+			}
+
+			const actionLabels = [
+				"➕ Create a new agent",
+				"🗑️ Delete an agent",
+				"⌨️ Change hotkey",
+				"📋 List all agents",
+				"🎨 Initialize default agent (builder)",
+			];
+			const actionChoice = await ctx.ui.select("Agents config", actionLabels);
+			if (!actionChoice) return;
+
+			const actionIdx = actionLabels.indexOf(actionChoice);
+			const actions = [
+				"create",
+				"delete",
+				"hotkey",
+				"list",
+				"init-defaults",
+			] as const;
+			const action = actions[actionIdx];
+			if (!action) return;
+
+			switch (action) {
+				case "create": {
+					const name = await ctx.ui.input(
+						"Agent name (e.g. debug, reviewer):",
+						"",
+					);
+					if (!name) return;
+					const displayName = await ctx.ui.input(
+						"Display name (e.g. 🐛 Debug):",
+						name,
+					);
+					if (!displayName) return;
+					const description = await ctx.ui.input("Short description:", "");
+					if (!description) return;
+					await createAgent(name, displayName, description, ctx);
+					break;
+				}
+				case "delete": {
+					const names = pm.getAgentNames();
+					if (names.length === 0) {
+						ctx.ui.notify("No custom agents to delete", "warning");
+						return;
+					}
+					const name = await ctx.ui.select("Pick agent to delete:", names);
+					if (!name) return;
+					const confirmed = await ctx.ui.confirm(
+						"Delete agent?",
+						`Delete "${name}" and its profile? This cannot be undone.`,
+					);
+					if (!confirmed) return;
+					try {
+						pm.delete(name);
+						if (currentAgent === name) {
+							currentAgent = PI_AGENT_NAME;
+							await restorePIState(ctx);
+							currentResolved = undefined;
+						}
+						updateStatus(ctx);
+						ctx.ui.notify(`Deleted agent: ${name}`, "info");
+					} catch (e: any) {
+						ctx.ui.notify(`Failed to delete: ${e.message}`, "error");
+					}
+					break;
+				}
+				case "hotkey": {
+					const keys: SelectItem[] = HOTKEY_CHOICES.map((h) => ({
+						value: h.key,
+						label: h.label,
+					}));
+					const key = await showSelectDialog(
+						ctx,
+						"Pick hotkey for agent cycling:",
+						keys,
+					);
+					if (!key) return;
+					const config = pm.loadConfig();
+					config.hotkey = key as KeyId;
+					pm.saveConfig(config);
+					ctx.ui.notify(
+						`Hotkey set to ${key}. Run /reload for it to take effect.`,
+						"info",
+					);
+					break;
+				}
+				case "list": {
+					const config = pm.loadConfig();
+					const active = pm.getActive(config);
+					const diskProfiles = pm.list();
+					const lines = diskProfiles.map((p) => {
+						const resolved = pm.resolveAgent(p.name, getPIState(), ctx.cwd);
+						const modelInfo = resolved?.model ? ` (${resolved.model})` : "";
+						const activeMarker = active === p.name ? " ★" : "";
+						return `  ${resolved?.label ?? p.name}${modelInfo}${activeMarker} — ${resolved?.description ?? ""}`;
+					});
+					pi.sendMessage({
+						customType: "agent-switch",
+						content: `# Agents\n\n${lines.join("\n")}`,
+						display: true,
+					});
+					break;
+				}
+				case "init-defaults": {
+					await initDefaults(ctx);
+					break;
+				}
+			}
+		},
+	});
+
+	// ─── Agent creation helpers ─────────────────────────
+
+	async function createAgent(
+		name: string,
+		displayName: string,
+		description: string,
+		ctx: ExtensionContext,
+	): Promise<void> {
+		try {
+			pm.create(name, { name: displayName, description });
+			ctx.ui.notify(
+				`Created agent "${name}". Edit ~/.pi/agents/${name}/AGENTS.md to customize.`,
+				"info",
+			);
+		} catch (e: any) {
+			ctx.ui.notify(e.message, "error");
+		}
+	}
+
+	async function initDefaults(ctx: ExtensionContext): Promise<void> {
+		let count = 0;
+		for (const [name, fm] of Object.entries(DEFAULT_AGENTS)) {
+			if (pm.exists(name)) continue;
+			try {
+				const prompt =
+					name === "builder"
+						? BUILDER_SYSTEM_PROMPT
+						: `# ${fm.name ?? name}\n\n${fm.description ?? ""}\n\nYou are the **${fm.name ?? name}** agent.\n`;
+				pm.create(name, fm, prompt);
+				count++;
+			} catch (e: any) {
+				ctx.ui.notify(`Failed to create ${name}: ${e.message}`, "error");
+			}
+		}
+		if (count > 0) {
+			loadCurrentAgent(pm.loadConfig());
+			ctx.ui.notify(`Initialized ${count} default agent(s)`, "info");
+		} else {
+			ctx.ui.notify("Default agents already initialized", "info");
+		}
+	}
+
+	// ─── Hotkey ─────────────────────────────────────────
+
+	function getHotkey(): KeyId {
+		const config = pm.loadConfig();
+		return (config.hotkey as KeyId | undefined) || DEFAULT_HOTKEY;
+	}
+
+	pi.registerShortcut(getHotkey(), {
+		description: "Cycle primary agent (PI → custom agents)",
+		handler: async (ctx) => {
+			initPM(ctx.cwd);
+			await cycleAgent(ctx);
+		},
+	});
+
+	// ─── before_agent_start ─────────────────────────────
+
+	pi.on("before_agent_start", async (event, ctx) => {
+		initPM(ctx.cwd);
+		loadCurrentAgent(pm.loadConfig());
+		await applyAgentSettings(ctx);
+		updateStatus(ctx);
+		const section = getAgentSystemPromptSection();
+		if (!section) return;
+
+		// Replace the default role line with the agent's identity banner.
+		// Everything else (tools, guidelines, skills, etc.) stays intact.
+		const roleStart = event.systemPrompt.indexOf(DEFAULT_ROLE_LINE);
+		if (roleStart >= 0) {
+			const roleEnd = roleStart + DEFAULT_ROLE_LINE.length;
+			const newPrompt =
+				event.systemPrompt.substring(0, roleStart) +
+				section +
+				event.systemPrompt.substring(roleEnd);
+			return { systemPrompt: newPrompt };
+		}
+
+		// Fallback: if the role line wasn't found (e.g. custom SYSTEM.md),
+		// prepend the agent section at the top instead of appending.
+		return { systemPrompt: section + "\n\n" + event.systemPrompt };
+	});
+
+	// ─── before_provider_request ────────────────────────
+
+	pi.on("before_provider_request", (event) => {
+		if (!currentResolved) return;
+		const payload = event.payload as Record<string, unknown>;
+		let changed = false;
+		if (currentResolved.temperature !== undefined) {
+			payload.temperature = currentResolved.temperature;
+			changed = true;
+		}
+		if (currentResolved.topP !== undefined) {
+			payload.top_p = currentResolved.topP;
+			changed = true;
+		}
+		if (changed) return payload;
+	});
+
+	// ─── Lifecycle ──────────────────────────────────────
+
+	pi.on("session_start", async (_event, ctx) => {
+		initPM(ctx.cwd);
+		loadCurrentAgent(pm.loadConfig());
+		if (currentAgent !== PI_AGENT_NAME)
+			currentResolved = pm.resolveAgent(currentAgent, getPIState(), ctx.cwd);
+		updateStatus(ctx);
+	});
+
+	pi.on("model_select", async (_event, ctx) => {
+		updateStatus(ctx);
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		ctx?.ui?.setStatus?.("agent-switch", undefined);
+	});
+}