@opengsd/gsd-pi 1.0.0

package/packages/pi-coding-agent/src/core/extensions/types.ts

@@ -0,0 +1,1872 @@
+/**
+ * Extension system types.
+ *
+ * Extensions are TypeScript modules that can:
+ * - Subscribe to agent lifecycle events
+ * - Register LLM-callable tools
+ * - Register commands, keyboard shortcuts, and CLI flags
+ * - Interact with the user via UI primitives
+ */
+
+import type {
+	AgentAbortOrigin,
+	AgentMessage,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	ThinkingLevel,
+} from "@gsd/pi-agent-core";
+import type {
+	Api,
+	AssistantMessageEvent,
+	AssistantMessageEventStream,
+	Context,
+	ImageContent,
+	Model,
+	OAuthCredentials,
+	OAuthLoginCallbacks,
+	SimpleStreamOptions,
+	TextContent,
+	ToolResultMessage,
+} from "@gsd/pi-ai";
+import type {
+	AutocompleteItem,
+	Component,
+	EditorComponent,
+	EditorTheme,
+	KeyId,
+	OverlayHandle,
+	OverlayOptions,
+	TUI,
+} from "@gsd/pi-tui";
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { Theme } from "../../modes/interactive/theme/theme.js";
+import type { BashResult } from "../bash-executor.js";
+import type { CompactionPreparation, CompactionResult } from "../compaction/index.js";
+import type { EventBus } from "../event-bus.js";
+import type { ExecOptions, ExecResult } from "../exec.js";
+import type { ReadonlyFooterDataProvider } from "../footer-data-provider.js";
+import type { KeybindingsManager } from "../keybindings.js";
+import type { CustomMessage } from "../messages.js";
+import type { ModelRegistry } from "../model-registry.js";
+import type {
+	BranchSummaryEntry,
+	CompactionEntry,
+	ReadonlySessionManager,
+	SessionEntry,
+	SessionManager,
+} from "../session-manager.js";
+import type { SlashCommandInfo } from "../slash-commands.js";
+import type { BashOperations } from "../tools/bash.js";
+import type { EditToolDetails } from "../tools/edit.js";
+import type {
+	BashToolDetails,
+	BashToolInput,
+	EditToolInput,
+	FindToolDetails,
+	FindToolInput,
+	GrepToolDetails,
+	GrepToolInput,
+	LsToolDetails,
+	LsToolInput,
+	ReadToolDetails,
+	ReadToolInput,
+	WriteToolDetails,
+	WriteToolInput,
+} from "../tools/index.js";
+
+export type { ExecOptions, ExecResult } from "../exec.js";
+export type { AgentToolResult, AgentToolUpdateCallback };
+export type { AppAction, KeybindingsManager } from "../keybindings.js";
+
+// ============================================================================
+// UI Context
+// ============================================================================
+
+/** Options for extension UI dialogs. */
+export interface ExtensionUIDialogOptions {
+	/** AbortSignal to programmatically dismiss the dialog. */
+	signal?: AbortSignal;
+	/** Timeout in milliseconds. Dialog auto-dismisses with live countdown display. */
+	timeout?: number;
+	/** When true, the user can select multiple options. The return type becomes `string[]`. */
+	allowMultiple?: boolean;
+	/** When true, text input dialogs should hide typed characters if supported by the client surface. */
+	secure?: boolean;
+}
+
+/** Placement for extension widgets. */
+export type WidgetPlacement = "aboveEditor" | "belowEditor";
+
+/** Options for extension widgets. */
+export interface ExtensionWidgetOptions {
+	/** Where the widget is rendered. Defaults to "aboveEditor". */
+	placement?: WidgetPlacement;
+}
+
+/** Raw terminal input listener for extensions. */
+export type TerminalInputHandler = (data: string) => { consume?: boolean; data?: string } | undefined;
+
+/**
+ * UI context for extensions to request interactive UI.
+ * Each mode (interactive, RPC, print) provides its own implementation.
+ */
+export interface ExtensionUIContext {
+	/** Show a selector and return the user's choice. When `opts.allowMultiple` is true, returns an array. */
+	select(title: string, options: string[], opts?: ExtensionUIDialogOptions): Promise<string | string[] | undefined>;
+
+	/** Show a confirmation dialog. */
+	confirm(title: string, message: string, opts?: ExtensionUIDialogOptions): Promise<boolean>;
+
+	/** Show a text input dialog. */
+	input(title: string, placeholder?: string, opts?: ExtensionUIDialogOptions): Promise<string | undefined>;
+
+	/** Show a notification to the user. */
+	notify(message: string, type?: "info" | "warning" | "error" | "success"): void;
+
+	/** Listen to raw terminal input (interactive mode only). Returns an unsubscribe function. */
+	onTerminalInput(handler: TerminalInputHandler): () => void;
+
+	/** Set status text in the footer/status bar. Pass undefined to clear. */
+	setStatus(key: string, text: string | undefined): void;
+
+	/** Set the working/loading message shown during streaming. Call with no argument to restore default; pass null to suppress it. */
+	setWorkingMessage(message?: string | null): void;
+
+	/** Set a widget to display above or below the editor. Accepts string array or component factory. */
+	setWidget(key: string, content: string[] | undefined, options?: ExtensionWidgetOptions): void;
+	setWidget(
+		key: string,
+		content: ((tui: TUI, theme: Theme) => Component & { dispose?(): void }) | undefined,
+		options?: ExtensionWidgetOptions,
+	): void;
+
+	/** Set a custom footer component, or undefined to restore the built-in footer.
+	 *
+	 * The factory receives a FooterDataProvider for data not otherwise accessible:
+	 * git branch and extension statuses from setStatus(). Token stats, model info,
+	 * etc. are available via ctx.sessionManager and ctx.model.
+	 */
+	setFooter(
+		factory:
+			| ((tui: TUI, theme: Theme, footerData: ReadonlyFooterDataProvider) => Component & { dispose?(): void })
+			| undefined,
+	): void;
+
+	/** Set a custom header component (shown at startup, above chat), or undefined to restore the built-in header. */
+	setHeader(factory: ((tui: TUI, theme: Theme) => Component & { dispose?(): void }) | undefined): void;
+
+	/** Set the terminal window/tab title. */
+	setTitle(title: string): void;
+
+	/** Show a custom component with keyboard focus. */
+	custom<T>(
+		factory: (
+			tui: TUI,
+			theme: Theme,
+			keybindings: KeybindingsManager,
+			done: (result: T) => void,
+		) => (Component & { dispose?(): void }) | Promise<Component & { dispose?(): void }>,
+		options?: {
+			overlay?: boolean;
+			/** Overlay positioning/sizing options. Can be static or a function for dynamic updates. */
+			overlayOptions?: OverlayOptions | (() => OverlayOptions);
+			/** Called with the overlay handle after the overlay is shown. Use to control visibility. */
+			onHandle?: (handle: OverlayHandle) => void;
+		},
+	): Promise<T>;
+
+	/** Paste text into the editor, triggering paste handling (collapse for large content). */
+	pasteToEditor(text: string): void;
+
+	/** Set the text in the core input editor. */
+	setEditorText(text: string): void;
+
+	/** Get the current text from the core input editor. */
+	getEditorText(): string;
+
+	/** Show a multi-line editor for text editing. */
+	editor(title: string, prefill?: string): Promise<string | undefined>;
+
+	/**
+	 * Set a custom editor component via factory function.
+	 * Pass undefined to restore the default editor.
+	 *
+	 * The factory receives:
+	 * - `theme`: EditorTheme for styling borders and autocomplete
+	 * - `keybindings`: KeybindingsManager for app-level keybindings
+	 *
+	 * For full app keybinding support (escape, ctrl+d, model switching, etc.),
+	 * extend `CustomEditor` from `@gsd/pi-coding-agent` and call
+	 * `super.handleInput(data)` for keys you don't handle.
+	 *
+	 * @example
+	 * ```ts
+	 * import { CustomEditor } from "@gsd/pi-coding-agent";
+	 *
+	 * class VimEditor extends CustomEditor {
+	 *   private mode: "normal" | "insert" = "insert";
+	 *
+	 *   handleInput(data: string): void {
+	 *     if (this.mode === "normal") {
+	 *       // Handle vim normal mode keys...
+	 *       if (data === "i") { this.mode = "insert"; return; }
+	 *     }
+	 *     super.handleInput(data);  // App keybindings + text editing
+	 *   }
+	 * }
+	 *
+	 * ctx.ui.setEditorComponent((tui, theme, keybindings) =>
+	 *   new VimEditor(tui, theme, keybindings)
+	 * );
+	 * ```
+	 */
+	setEditorComponent(
+		factory: ((tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) => EditorComponent) | undefined,
+	): void;
+
+	/** Get the current theme for styling. */
+	readonly theme: Theme;
+
+	/** Get all available themes with their names and file paths. */
+	getAllThemes(): { name: string; path: string | undefined }[];
+
+	/** Load a theme by name without switching to it. Returns undefined if not found. */
+	getTheme(name: string): Theme | undefined;
+
+	/** Set the current theme by name or Theme object. */
+	setTheme(theme: string | Theme): { success: boolean; error?: string };
+
+	/** Get current tool output expansion state. */
+	getToolsExpanded(): boolean;
+
+	/** Set tool output expansion state. */
+	setToolsExpanded(expanded: boolean): void;
+}
+
+// ============================================================================
+// Extension Context
+// ============================================================================
+
+export interface ContextUsage {
+	/** Estimated context tokens, or null if unknown (e.g. right after compaction, before next LLM response). */
+	tokens: number | null;
+	contextWindow: number;
+	/** Context usage as percentage of context window, or null if tokens is unknown. */
+	percent: number | null;
+}
+
+export interface CompactOptions {
+	customInstructions?: string;
+	onComplete?: (result: CompactionResult) => void;
+	onError?: (error: Error) => void;
+}
+
+/**
+ * Context passed to extension event handlers.
+ */
+export interface ExtensionContext {
+	/** UI methods for user interaction */
+	ui: ExtensionUIContext;
+	/** Whether UI is available (false in print/RPC mode) */
+	hasUI: boolean;
+	/** Current working directory */
+	cwd: string;
+	/** Session manager (read-only) */
+	sessionManager: ReadonlySessionManager;
+	/** Model registry for API key resolution */
+	modelRegistry: ModelRegistry;
+	/** Current model (may be undefined) */
+	model: Model<any> | undefined;
+	/** Whether the agent is idle (not streaming) */
+	isIdle(): boolean;
+	/** Abort the current agent operation */
+	abort(): void;
+	/** Whether there are queued messages waiting */
+	hasPendingMessages(): boolean;
+	/** Gracefully shutdown pi and exit. Available in all contexts. */
+	shutdown(): void;
+	/** Get current context usage for the active model. */
+	getContextUsage(): ContextUsage | undefined;
+	/** Trigger compaction without awaiting completion. */
+	compact(options?: CompactOptions): void;
+	/** Get the current effective system prompt. */
+	getSystemPrompt(): string;
+	/**
+	 * Set or clear an in-memory compaction threshold-percent override (0 < value < 1).
+	 * Pass `undefined` to clear. The override is not persisted; host integrations
+	 * are expected to re-apply on each session_start.
+	 */
+	setCompactionThresholdOverride(percent: number | undefined): void;
+}
+
+/**
+ * Extended context for command handlers.
+ * Includes session control methods only safe in user-initiated commands.
+ */
+export interface ExtensionCommandContext extends ExtensionContext {
+	/** Wait for the agent to finish streaming */
+	waitForIdle(): Promise<void>;
+
+	/** Start a new session, optionally with initialization. */
+	newSession(options?: {
+		parentSession?: string;
+		setup?: (sessionManager: SessionManager) => Promise<void>;
+		/** Explicit workspace root for the new session/tool runtime.
+		 *  When omitted, newSession() captures process.cwd() for backwards compatibility. */
+		workspaceRoot?: string;
+		/** When aborted before the session is fully configured, newSession() returns
+		 *  early without rebuilding the tool runtime. Used by runUnit() to discard
+		 *  a late-resolving newSession() after the session-creation timeout fires,
+		 *  preventing the tool runtime from being rebuilt with a stale workspace root (#3731). */
+		abortSignal?: AbortSignal;
+	}): Promise<{ cancelled: boolean }>;
+
+	/** Fork from a specific entry, creating a new session file. */
+	fork(entryId: string): Promise<{ cancelled: boolean }>;
+
+	/** Navigate to a different point in the session tree. */
+	navigateTree(
+		targetId: string,
+		options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string },
+	): Promise<{ cancelled: boolean }>;
+
+	/** Switch to a different session file. */
+	switchSession(sessionPath: string): Promise<{ cancelled: boolean }>;
+
+	/** Reload extensions, skills, prompts, and themes. */
+	reload(): Promise<void>;
+}
+
+// ============================================================================
+// Tool Types
+// ============================================================================
+
+/** Rendering options for tool results */
+export interface ToolRenderResultOptions {
+	/** Whether the result view is expanded */
+	expanded: boolean;
+	/** Whether this is a partial/streaming result */
+	isPartial: boolean;
+}
+
+/**
+ * Tool compatibility metadata for provider-aware tool filtering (ADR-005 Phase 2).
+ * Tools without compatibility metadata are assumed universally compatible.
+ */
+export interface ToolCompatibility {
+	/** Tool produces image content in results (filtered for providers without imageToolResults) */
+	producesImages?: boolean;
+	/** Tool requires schema features that some providers don't support (e.g., ["patternProperties"]) */
+	schemaFeatures?: string[];
+	/** Tool is effective only with models above a minimum capability threshold */
+	minCapabilityTier?: "light" | "standard" | "heavy";
+}
+
+/**
+ * Tool definition for registerTool().
+ */
+export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown> {
+	/** Tool name (used in LLM tool calls) */
+	name: string;
+	/** Human-readable label for UI */
+	label: string;
+	/** Description for LLM */
+	description: string;
+	/** Optional one-line snippet for the Available tools section in the default system prompt. Falls back to description when omitted. */
+	promptSnippet?: string;
+	/** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
+	promptGuidelines?: string[];
+	/** Parameter schema (TypeBox) */
+	parameters: TParams;
+	/** Provider compatibility metadata (ADR-005). Omit for universally compatible tools. */
+	compatibility?: ToolCompatibility;
+
+	/** Execute the tool. */
+	execute(
+		toolCallId: string,
+		params: Static<TParams>,
+		signal: AbortSignal | undefined,
+		onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
+		ctx: ExtensionContext,
+	): Promise<AgentToolResult<TDetails>>;
+
+	/** Custom rendering for tool call display */
+	renderCall?: (args: Static<TParams>, theme: Theme) => Component | undefined;
+
+	/** Custom rendering for tool result display */
+	renderResult?: (
+		result: AgentToolResult<TDetails>,
+		options: ToolRenderResultOptions,
+		theme: Theme,
+	) => Component | undefined;
+}
+
+// ============================================================================
+// Resource Events
+// ============================================================================
+
+/** Fired after session_start to allow extensions to provide additional resource paths. */
+export interface ResourcesDiscoverEvent {
+	type: "resources_discover";
+	cwd: string;
+	reason: "startup" | "reload";
+}
+
+/** Result from resources_discover event handler */
+export interface ResourcesDiscoverResult {
+	skillPaths?: string[];
+	promptPaths?: string[];
+	themePaths?: string[];
+}
+
+// ============================================================================
+// Session Events
+// ============================================================================
+
+/** Fired before session manager creation to allow custom session directory resolution */
+export interface SessionDirectoryEvent {
+	type: "session_directory";
+	cwd: string;
+}
+
+/** Fired on initial session load */
+export interface SessionStartEvent {
+	type: "session_start";
+}
+
+/** Fired before switching to another session (can be cancelled) */
+export interface SessionBeforeSwitchEvent {
+	type: "session_before_switch";
+	reason: "new" | "resume";
+	targetSessionFile?: string;
+}
+
+/** Fired after switching to another session */
+export interface SessionSwitchEvent {
+	type: "session_switch";
+	reason: "new" | "resume";
+	previousSessionFile: string | undefined;
+}
+
+/** Fired before forking a session (can be cancelled) */
+export interface SessionBeforeForkEvent {
+	type: "session_before_fork";
+	entryId: string;
+}
+
+/** Fired after forking a session */
+export interface SessionForkEvent {
+	type: "session_fork";
+	previousSessionFile: string | undefined;
+}
+
+/** Fired before context compaction (can be cancelled or customized) */
+export interface SessionBeforeCompactEvent {
+	type: "session_before_compact";
+	preparation: CompactionPreparation;
+	branchEntries: SessionEntry[];
+	customInstructions?: string;
+	signal: AbortSignal;
+}
+
+/** Fired after context compaction */
+export interface SessionCompactEvent {
+	type: "session_compact";
+	compactionEntry: CompactionEntry;
+	fromExtension: boolean;
+}
+
+/** Fired on process exit */
+export interface SessionShutdownEvent {
+	type: "session_shutdown";
+}
+
+/** Fired when the in-process session ends (distinct from process shutdown). */
+export interface SessionEndEvent {
+	type: "session_end";
+	reason: "user" | "idle" | "error" | "programmatic";
+	sessionFile?: string;
+}
+
+/** Preparation data for tree navigation */
+export interface TreePreparation {
+	targetId: string;
+	oldLeafId: string | null;
+	commonAncestorId: string | null;
+	entriesToSummarize: SessionEntry[];
+	userWantsSummary: boolean;
+	/** Custom instructions for summarization */
+	customInstructions?: string;
+	/** If true, customInstructions replaces the default prompt instead of being appended */
+	replaceInstructions?: boolean;
+	/** Label to attach to the branch summary entry */
+	label?: string;
+}
+
+/** Fired before navigating in the session tree (can be cancelled) */
+export interface SessionBeforeTreeEvent {
+	type: "session_before_tree";
+	preparation: TreePreparation;
+	signal: AbortSignal;
+}
+
+/** Fired after navigating in the session tree */
+export interface SessionTreeEvent {
+	type: "session_tree";
+	newLeafId: string | null;
+	oldLeafId: string | null;
+	summaryEntry?: BranchSummaryEntry;
+	fromExtension?: boolean;
+}
+
+export type SessionEvent =
+	| SessionDirectoryEvent
+	| SessionStartEvent
+	| SessionBeforeSwitchEvent
+	| SessionSwitchEvent
+	| SessionBeforeForkEvent
+	| SessionForkEvent
+	| SessionBeforeCompactEvent
+	| SessionCompactEvent
+	| SessionShutdownEvent
+	| SessionEndEvent
+	| SessionBeforeTreeEvent
+	| SessionTreeEvent;
+
+// ============================================================================
+// Agent Events
+// ============================================================================
+
+/** Fired before each LLM call. Can modify messages. */
+export interface ContextEvent {
+	type: "context";
+	messages: AgentMessage[];
+}
+
+/** Fired before a provider request is sent. Can replace the payload. */
+export interface BeforeProviderRequestEvent {
+	type: "before_provider_request";
+	payload: unknown;
+	/** The resolved model for this request (provider, id, api, etc.) */
+	model?: { provider: string; id: string; api?: string };
+}
+
+/** Fired after user submits prompt but before agent loop. */
+export interface BeforeAgentStartEvent {
+	type: "before_agent_start";
+	prompt: string;
+	images?: ImageContent[];
+	systemPrompt: string;
+}
+
+/** Fired when an agent loop starts */
+export interface AgentStartEvent {
+	type: "agent_start";
+	sessionId?: string;
+	turnId?: string;
+}
+
+/** Fired when an agent loop ends */
+export interface AgentEndEvent {
+	type: "agent_end";
+	messages: AgentMessage[];
+	sessionId?: string;
+	turnId?: string;
+	abortOrigin?: AgentAbortOrigin;
+}
+
+/**
+ * Fired when the agent has truly stopped — no follow-up, no steering, no pending turn.
+ * Distinct from `agent_end`, which fires on every loop exit (including those that resume).
+ * Use this for "the agent is idle and waiting for the user" signals.
+ */
+export interface StopEvent {
+	type: "stop";
+	reason: "completed" | "cancelled" | "error" | "blocked";
+	lastMessage?: AgentMessage;
+	sessionId?: string;
+	turnId?: string;
+	abortOrigin?: AgentAbortOrigin;
+}
+
+/**
+ * Fired when the agent needs user attention (blocked on a question, idle, milestone ready).
+ * Consumed by the Layer 0 shell-hook runner to dispatch `Notification` / `Blocked` hooks.
+ */
+export interface NotificationEvent {
+	type: "notification";
+	kind: "blocked" | "input_needed" | "milestone_ready" | "idle" | "error";
+	message: string;
+	details?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Git Lifecycle Events
+// ============================================================================
+
+/** Fired before a commit is created. Handlers can veto or rewrite the message. */
+export interface BeforeCommitEvent {
+	type: "before_commit";
+	message: string;
+	files: string[];
+	cwd: string;
+	author?: string;
+}
+
+/** Result from before_commit event handler. */
+export interface BeforeCommitEventResult {
+	cancel?: boolean;
+	reason?: string;
+	message?: string;
+}
+
+/** Fired after a commit lands. */
+export interface CommitEvent {
+	type: "commit";
+	sha: string;
+	message: string;
+	files: string[];
+	cwd: string;
+}
+
+/** Fired before a git push. Handlers can veto. */
+export interface BeforePushEvent {
+	type: "before_push";
+	remote: string;
+	branch: string;
+	cwd: string;
+}
+
+/** Result from before_push event handler. */
+export interface BeforePushEventResult {
+	cancel?: boolean;
+	reason?: string;
+}
+
+/** Fired after a push completes. */
+export interface PushEvent {
+	type: "push";
+	remote: string;
+	branch: string;
+	cwd: string;
+}
+
+/** Fired before a pull request is opened. Handlers can veto or rewrite title/body. */
+export interface BeforePrEvent {
+	type: "before_pr";
+	branch: string;
+	targetBranch: string;
+	title: string;
+	body: string;
+	cwd: string;
+}
+
+/** Result from before_pr event handler. */
+export interface BeforePrEventResult {
+	cancel?: boolean;
+	reason?: string;
+	title?: string;
+	body?: string;
+}
+
+/** Fired after a pull request is opened. */
+export interface PrOpenedEvent {
+	type: "pr_opened";
+	url: string;
+	branch: string;
+	targetBranch: string;
+	cwd: string;
+}
+
+// ============================================================================
+// Verification Events
+// ============================================================================
+
+/** Fired before verification runs (tests, diagnostics, gates). */
+export interface BeforeVerifyEvent {
+	type: "before_verify";
+	unitType?: string;
+	unitId?: string;
+	cwd: string;
+}
+
+/** Result from before_verify event handler. */
+export interface BeforeVerifyEventResult {
+	cancel?: boolean;
+	reason?: string;
+}
+
+/** A single verification failure. */
+export interface VerifyFailure {
+	kind: "type" | "lint" | "test" | "diagnostic" | "gate" | "other";
+	file?: string;
+	line?: number;
+	message: string;
+}
+
+/** Fired when verification completes. */
+export interface VerifyResultEvent {
+	type: "verify_result";
+	passed: boolean;
+	failures: VerifyFailure[];
+	unitType?: string;
+	unitId?: string;
+	cwd: string;
+}
+
+// ============================================================================
+// Budget Events
+// ============================================================================
+
+/** Fired when the tracked cost crosses a configured fraction of the budget. */
+export interface BudgetThresholdEvent {
+	type: "budget_threshold";
+	fraction: number;
+	spent: number;
+	limit: number;
+	currency: "USD";
+}
+
+/** Result from budget_threshold event handler. */
+export interface BudgetThresholdEventResult {
+	action?: "pause" | "downgrade" | "continue";
+}
+
+// ============================================================================
+// Orchestrator Events (milestone / unit boundaries)
+// ============================================================================
+
+/** Fired at the start of an orchestrator milestone. */
+export interface MilestoneStartEvent {
+	type: "milestone_start";
+	milestoneId: string;
+	title?: string;
+	cwd: string;
+}
+
+/** Fired when a milestone ends. */
+export interface MilestoneEndEvent {
+	type: "milestone_end";
+	milestoneId: string;
+	status: "completed" | "failed" | "cancelled";
+	cwd: string;
+}
+
+/** Fired at the start of an orchestrator unit (sub-task within a milestone). */
+export interface UnitStartEvent {
+	type: "unit_start";
+	unitType: string;
+	unitId: string;
+	milestoneId?: string;
+	cwd: string;
+}
+
+/** Fired when a unit ends. */
+export interface UnitEndEvent {
+	type: "unit_end";
+	unitType: string;
+	unitId: string;
+	milestoneId?: string;
+	status: "completed" | "failed" | "cancelled" | "blocked";
+	cwd: string;
+}
+
+/** Fired at the start of each turn */
+export interface TurnStartEvent {
+	type: "turn_start";
+	turnIndex: number;
+	timestamp: number;
+	sessionId?: string;
+	turnId?: string;
+}
+
+/** Fired at the end of each turn */
+export interface TurnEndEvent {
+	type: "turn_end";
+	turnIndex: number;
+	message: AgentMessage;
+	toolResults: ToolResultMessage[];
+	sessionId?: string;
+	turnId?: string;
+}
+
+/** Fired when a message starts (user, assistant, or toolResult) */
+export interface MessageStartEvent {
+	type: "message_start";
+	message: AgentMessage;
+	sessionId?: string;
+	turnId?: string;
+}
+
+/** Fired during assistant message streaming with token-by-token updates */
+export interface MessageUpdateEvent {
+	type: "message_update";
+	message: AgentMessage;
+	assistantMessageEvent: AssistantMessageEvent;
+	sessionId?: string;
+	turnId?: string;
+}
+
+/** Fired when a message ends */
+export interface MessageEndEvent {
+	type: "message_end";
+	message: AgentMessage;
+	sessionId?: string;
+	turnId?: string;
+}
+
+/** Fired when a tool starts executing */
+export interface ToolExecutionStartEvent {
+	type: "tool_execution_start";
+	toolCallId: string;
+	toolName: string;
+	args: any;
+}
+
+/** Fired during tool execution with partial/streaming output */
+export interface ToolExecutionUpdateEvent {
+	type: "tool_execution_update";
+	toolCallId: string;
+	toolName: string;
+	args: any;
+	partialResult: any;
+}
+
+/** Fired when a tool finishes executing */
+export interface ToolExecutionEndEvent {
+	type: "tool_execution_end";
+	toolCallId: string;
+	toolName: string;
+	result: any;
+	isError: boolean;
+}
+
+// ============================================================================
+// Model Events
+// ============================================================================
+
+export type ModelSelectSource = "set" | "cycle" | "restore";
+
+/** Fired when a new model is selected */
+export interface ModelSelectEvent {
+	type: "model_select";
+	model: Model<any>;
+	previousModel: Model<any> | undefined;
+	source: ModelSelectSource;
+}
+
+/** Fired before model selection runs capability scoring. Extensions can override the selected model. */
+export interface BeforeModelSelectEvent {
+	type: "before_model_select";
+	unitType: string;
+	unitId: string;
+	classification: { tier: string; reason: string; downgraded: boolean };
+	taskMetadata?: Record<string, unknown>;
+	eligibleModels: string[];
+	phaseConfig?: { primary: string; fallbacks: string[] };
+}
+
+/** Result from before_model_select event handler. Return { modelId } to override selection. */
+export interface BeforeModelSelectResult {
+	modelId: string;
+}
+
+export interface AdjustToolSetRequestCustomMessage {
+	/** Index in the post-transform AgentMessage context. */
+	index: number;
+	/** Custom message type only; prompt/content text is intentionally omitted. */
+	customType: string;
+}
+
+/**
+ * Fired after model selection to allow extensions to adjust the active tool set (ADR-005 Phase 4).
+ * Extensions can add, remove, or reorder tools based on the selected model's provider capabilities.
+ */
+export interface AdjustToolSetEvent {
+	type: "adjust_tool_set";
+	/** The selected model's API type */
+	selectedModelApi: string;
+	/** The selected model's provider */
+	selectedModelProvider: string;
+	/** The selected model ID */
+	selectedModelId: string;
+	/** Current active tool names */
+	activeToolNames: string[];
+	/** Tools already filtered by provider compatibility */
+	filteredTools: string[];
+	/**
+	 * Custom message metadata in the current request tail, measured from the
+	 * latest assistant message. This is metadata-only so extensions can scope
+	 * queued custom-message turns without seeing raw prompt content.
+	 */
+	requestCustomMessages?: AdjustToolSetRequestCustomMessage[];
+}
+
+/** Result from adjust_tool_set event handler. Return { toolNames } to override tool set. */
+export interface AdjustToolSetResult {
+	/** Replacement tool names. If omitted, the default filtering is used. */
+	toolNames?: string[];
+}
+
+// ============================================================================
+// User Bash Events
+// ============================================================================
+
+/**
+ * Fired before the bash tool executes a shell command.
+ * Extensions can return a transformed command string.
+ * All registered handlers are called in order; each receives the output of the previous.
+ */
+export interface BashTransformEvent {
+	type: "bash_transform";
+	/** The command string about to be executed */
+	command: string;
+	/** Current working directory */
+	cwd: string;
+}
+
+/** Result from bash_transform event handler */
+export interface BashTransformEventResult {
+	/** Replacement command string. If omitted or empty, the original command is used. */
+	command?: string;
+}
+
+/** Fired when user executes a bash command via ! or !! prefix */
+export interface UserBashEvent {
+	type: "user_bash";
+	/** The command to execute */
+	command: string;
+	/** True if !! prefix was used (excluded from LLM context) */
+	excludeFromContext: boolean;
+	/** Current working directory */
+	cwd: string;
+}
+
+// ============================================================================
+// Input Events
+// ============================================================================
+
+/** Source of user input */
+export type InputSource = "interactive" | "rpc" | "extension";
+
+/** Fired when user input is received, before agent processing */
+export interface InputEvent {
+	type: "input";
+	/** The input text */
+	text: string;
+	/** Attached images, if any */
+	images?: ImageContent[];
+	/** Where the input came from */
+	source: InputSource;
+}
+
+/** Result from input event handler */
+export type InputEventResult =
+	| { action: "continue" }
+	| { action: "transform"; text: string; images?: ImageContent[] }
+	| { action: "handled" };
+
+// ============================================================================
+// Tool Events
+// ============================================================================
+
+interface ToolCallEventBase {
+	type: "tool_call";
+	toolCallId: string;
+}
+
+export interface BashToolCallEvent extends ToolCallEventBase {
+	toolName: "bash";
+	input: BashToolInput;
+}
+
+export interface ReadToolCallEvent extends ToolCallEventBase {
+	toolName: "read";
+	input: ReadToolInput;
+}
+
+export interface EditToolCallEvent extends ToolCallEventBase {
+	toolName: "edit";
+	input: EditToolInput;
+}
+
+export interface WriteToolCallEvent extends ToolCallEventBase {
+	toolName: "write";
+	input: WriteToolInput;
+}
+
+export interface GrepToolCallEvent extends ToolCallEventBase {
+	toolName: "grep";
+	input: GrepToolInput;
+}
+
+export interface FindToolCallEvent extends ToolCallEventBase {
+	toolName: "find";
+	input: FindToolInput;
+}
+
+export interface LsToolCallEvent extends ToolCallEventBase {
+	toolName: "ls";
+	input: LsToolInput;
+}
+
+export interface CustomToolCallEvent extends ToolCallEventBase {
+	toolName: string;
+	input: Record<string, unknown>;
+}
+
+/** Fired before a tool executes. Can block. */
+export type ToolCallEvent =
+	| BashToolCallEvent
+	| ReadToolCallEvent
+	| EditToolCallEvent
+	| WriteToolCallEvent
+	| GrepToolCallEvent
+	| FindToolCallEvent
+	| LsToolCallEvent
+	| CustomToolCallEvent;
+
+interface ToolResultEventBase {
+	type: "tool_result";
+	toolCallId: string;
+	input: Record<string, unknown>;
+	content: (TextContent | ImageContent)[];
+	isError: boolean;
+}
+
+export interface BashToolResultEvent extends ToolResultEventBase {
+	toolName: "bash";
+	details: BashToolDetails | undefined;
+}
+
+export interface ReadToolResultEvent extends ToolResultEventBase {
+	toolName: "read";
+	details: ReadToolDetails | undefined;
+}
+
+export interface EditToolResultEvent extends ToolResultEventBase {
+	toolName: "edit";
+	details: EditToolDetails | undefined;
+}
+
+export interface WriteToolResultEvent extends ToolResultEventBase {
+	toolName: "write";
+	details: WriteToolDetails | undefined;
+}
+
+export interface GrepToolResultEvent extends ToolResultEventBase {
+	toolName: "grep";
+	details: GrepToolDetails | undefined;
+}
+
+export interface FindToolResultEvent extends ToolResultEventBase {
+	toolName: "find";
+	details: FindToolDetails | undefined;
+}
+
+export interface LsToolResultEvent extends ToolResultEventBase {
+	toolName: "ls";
+	details: LsToolDetails | undefined;
+}
+
+export interface CustomToolResultEvent extends ToolResultEventBase {
+	toolName: string;
+	details: unknown;
+}
+
+/** Fired after a tool executes. Can modify result. */
+export type ToolResultEvent =
+	| BashToolResultEvent
+	| ReadToolResultEvent
+	| EditToolResultEvent
+	| WriteToolResultEvent
+	| GrepToolResultEvent
+	| FindToolResultEvent
+	| LsToolResultEvent
+	| CustomToolResultEvent;
+
+/**
+ * Type guard for narrowing ToolResultEvent by tool name.
+ *
+ * Built-in tools narrow automatically (no type params needed):
+ * ```ts
+ * if (isToolResultEventType("bash", event)) {
+ *   event.details;  // BashToolDetails | undefined
+ * }
+ * ```
+ *
+ * Custom tools require explicit type parameters:
+ * ```ts
+ * if (isToolResultEventType<"my_tool", MyDetails>("my_tool", event)) {
+ *   event.details;  // typed
+ * }
+ * ```
+ */
+export function isToolResultEventType(toolName: "bash", event: ToolResultEvent): event is BashToolResultEvent;
+export function isToolResultEventType(toolName: "read", event: ToolResultEvent): event is ReadToolResultEvent;
+export function isToolResultEventType(toolName: "edit", event: ToolResultEvent): event is EditToolResultEvent;
+export function isToolResultEventType(toolName: "write", event: ToolResultEvent): event is WriteToolResultEvent;
+export function isToolResultEventType(toolName: "grep", event: ToolResultEvent): event is GrepToolResultEvent;
+export function isToolResultEventType(toolName: "find", event: ToolResultEvent): event is FindToolResultEvent;
+export function isToolResultEventType(toolName: "ls", event: ToolResultEvent): event is LsToolResultEvent;
+export function isToolResultEventType<TName extends string, TDetails = unknown>(
+	toolName: TName,
+	event: ToolResultEvent,
+): event is ToolResultEvent & { toolName: TName; details: TDetails };
+export function isToolResultEventType(toolName: string, event: ToolResultEvent): boolean {
+	return event.toolName === toolName;
+}
+
+/**
+ * Type guard for narrowing ToolCallEvent by tool name.
+ *
+ * Built-in tools narrow automatically (no type params needed):
+ * ```ts
+ * if (isToolCallEventType("bash", event)) {
+ *   event.input.command;  // string
+ * }
+ * ```
+ *
+ * Custom tools require explicit type parameters:
+ * ```ts
+ * if (isToolCallEventType<"my_tool", MyToolInput>("my_tool", event)) {
+ *   event.input.action;  // typed
+ * }
+ * ```
+ *
+ * Note: Direct narrowing via `event.toolName === "bash"` doesn't work because
+ * CustomToolCallEvent.toolName is `string` which overlaps with all literals.
+ */
+export function isToolCallEventType(toolName: "bash", event: ToolCallEvent): event is BashToolCallEvent;
+export function isToolCallEventType(toolName: "read", event: ToolCallEvent): event is ReadToolCallEvent;
+export function isToolCallEventType(toolName: "edit", event: ToolCallEvent): event is EditToolCallEvent;
+export function isToolCallEventType(toolName: "write", event: ToolCallEvent): event is WriteToolCallEvent;
+export function isToolCallEventType(toolName: "grep", event: ToolCallEvent): event is GrepToolCallEvent;
+export function isToolCallEventType(toolName: "find", event: ToolCallEvent): event is FindToolCallEvent;
+export function isToolCallEventType(toolName: "ls", event: ToolCallEvent): event is LsToolCallEvent;
+export function isToolCallEventType<TName extends string, TInput extends Record<string, unknown>>(
+	toolName: TName,
+	event: ToolCallEvent,
+): event is ToolCallEvent & { toolName: TName; input: TInput };
+export function isToolCallEventType(toolName: string, event: ToolCallEvent): boolean {
+	return event.toolName === toolName;
+}
+
+/** Union of all event types */
+export type ExtensionEvent =
+	| ResourcesDiscoverEvent
+	| SessionEvent
+	| ContextEvent
+	| BeforeProviderRequestEvent
+	| BeforeAgentStartEvent
+	| AgentStartEvent
+	| AgentEndEvent
+	| StopEvent
+	| NotificationEvent
+	| BeforeCommitEvent
+	| CommitEvent
+	| BeforePushEvent
+	| PushEvent
+	| BeforePrEvent
+	| PrOpenedEvent
+	| BeforeVerifyEvent
+	| VerifyResultEvent
+	| BudgetThresholdEvent
+	| MilestoneStartEvent
+	| MilestoneEndEvent
+	| UnitStartEvent
+	| UnitEndEvent
+	| TurnStartEvent
+	| TurnEndEvent
+	| MessageStartEvent
+	| MessageUpdateEvent
+	| MessageEndEvent
+	| ToolExecutionStartEvent
+	| ToolExecutionUpdateEvent
+	| ToolExecutionEndEvent
+	| ModelSelectEvent
+	| BashTransformEvent
+	| UserBashEvent
+	| InputEvent
+	| ToolCallEvent
+	| ToolResultEvent;
+
+// ============================================================================
+// Event Results
+// ============================================================================
+
+export interface ContextEventResult {
+	messages?: AgentMessage[];
+}
+
+export type BeforeProviderRequestEventResult = unknown;
+
+export interface ToolCallEventResult {
+	block?: boolean;
+	reason?: string;
+}
+
+/** Result from user_bash event handler */
+export interface UserBashEventResult {
+	/** Custom operations to use for execution */
+	operations?: BashOperations;
+	/** Full replacement: extension handled execution, use this result */
+	result?: BashResult;
+}
+
+export interface ToolResultEventResult {
+	content?: (TextContent | ImageContent)[];
+	details?: unknown;
+	isError?: boolean;
+}
+
+export interface BeforeAgentStartEventResult {
+	message?: Pick<CustomMessage, "customType" | "content" | "display" | "details">;
+	/** Replace the system prompt for this turn. If multiple extensions return this, they are chained. */
+	systemPrompt?: string;
+}
+
+export interface SessionDirectoryResult {
+	/** Custom session directory path. If multiple extensions return this, the last one wins. */
+	sessionDir?: string;
+}
+
+/** Special startup-only handler. Unlike other events, this receives no ExtensionContext. */
+export type SessionDirectoryHandler = (
+	event: SessionDirectoryEvent,
+) => Promise<SessionDirectoryResult | undefined> | SessionDirectoryResult | undefined;
+
+export interface SessionBeforeSwitchResult {
+	cancel?: boolean;
+}
+
+export interface SessionBeforeForkResult {
+	cancel?: boolean;
+	skipConversationRestore?: boolean;
+}
+
+export interface SessionBeforeCompactResult {
+	cancel?: boolean;
+	compaction?: CompactionResult;
+}
+
+export interface SessionBeforeTreeResult {
+	cancel?: boolean;
+	summary?: {
+		summary: string;
+		details?: unknown;
+	};
+	/** Override custom instructions for summarization */
+	customInstructions?: string;
+	/** Override whether customInstructions replaces the default prompt */
+	replaceInstructions?: boolean;
+	/** Override label to attach to the branch summary entry */
+	label?: string;
+}
+
+// ============================================================================
+// Message Rendering
+// ============================================================================
+
+export interface MessageRenderOptions {
+	expanded: boolean;
+}
+
+export type MessageRenderer<T = unknown> = (
+	message: CustomMessage<T>,
+	options: MessageRenderOptions,
+	theme: Theme,
+) => Component | undefined;
+
+// ============================================================================
+// Command Registration
+// ============================================================================
+
+export interface RegisteredCommand {
+	name: string;
+	description?: string;
+	getArgumentCompletions?: (argumentPrefix: string) => AutocompleteItem[] | null;
+	handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
+}
+
+export type LifecycleHookScope = "user" | "project";
+export type LifecycleHookPhase = "beforeInstall" | "afterInstall" | "beforeRemove" | "afterRemove";
+
+export interface LifecycleHookContext {
+	/** Lifecycle phase currently being executed. */
+	phase: LifecycleHookPhase;
+	/** Package source string passed to install (npm:, git:, https://, local path). */
+	source: string;
+	/** Resolved installed package path (or resolved local path), when available for this phase. */
+	installedPath?: string;
+	/** Where the package was installed. */
+	scope: LifecycleHookScope;
+	/** Current working directory for the install invocation. */
+	cwd: string;
+	/** Whether install is running in an interactive TTY. */
+	interactive: boolean;
+	/** Info-level logging sink for install output. */
+	log(message: string): void;
+	/** Warning-level logging sink for install output. */
+	warn(message: string): void;
+	/** Error-level logging sink for install output. */
+	error(message: string): void;
+}
+
+export type LifecycleHookHandler = (ctx: LifecycleHookContext) => Promise<void> | void;
+export type LifecycleHookMap = Record<LifecycleHookPhase, LifecycleHookHandler[]>;
+
+// ============================================================================
+// Extension API
+// ============================================================================
+
+/** Handler function type for events */
+// biome-ignore lint/suspicious/noConfusingVoidType: void allows bare return statements
+export type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContext) => Promise<R | void> | R | void;
+
+/**
+ * ExtensionAPI passed to extension factory functions.
+ */
+export interface ExtensionAPI {
+	// =========================================================================
+	// Event Subscription
+	// =========================================================================
+
+	on(event: "resources_discover", handler: ExtensionHandler<ResourcesDiscoverEvent, ResourcesDiscoverResult>): void;
+	on(event: "session_directory", handler: SessionDirectoryHandler): void;
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+	on(
+		event: "session_before_switch",
+		handler: ExtensionHandler<SessionBeforeSwitchEvent, SessionBeforeSwitchResult>,
+	): void;
+	on(event: "session_switch", handler: ExtensionHandler<SessionSwitchEvent>): void;
+	on(event: "session_before_fork", handler: ExtensionHandler<SessionBeforeForkEvent, SessionBeforeForkResult>): void;
+	on(event: "session_fork", handler: ExtensionHandler<SessionForkEvent>): void;
+	on(
+		event: "session_before_compact",
+		handler: ExtensionHandler<SessionBeforeCompactEvent, SessionBeforeCompactResult>,
+	): void;
+	on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
+	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
+	on(event: "session_end", handler: ExtensionHandler<SessionEndEvent>): void;
+	on(event: "session_before_tree", handler: ExtensionHandler<SessionBeforeTreeEvent, SessionBeforeTreeResult>): void;
+	on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>): void;
+	on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>): void;
+	on(
+		event: "before_provider_request",
+		handler: ExtensionHandler<BeforeProviderRequestEvent, BeforeProviderRequestEventResult>,
+	): void;
+	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
+	on(event: "agent_start", handler: ExtensionHandler<AgentStartEvent>): void;
+	on(event: "agent_end", handler: ExtensionHandler<AgentEndEvent>): void;
+	on(event: "stop", handler: ExtensionHandler<StopEvent>): void;
+	on(event: "notification", handler: ExtensionHandler<NotificationEvent>): void;
+	on(event: "before_commit", handler: ExtensionHandler<BeforeCommitEvent, BeforeCommitEventResult>): void;
+	on(event: "commit", handler: ExtensionHandler<CommitEvent>): void;
+	on(event: "before_push", handler: ExtensionHandler<BeforePushEvent, BeforePushEventResult>): void;
+	on(event: "push", handler: ExtensionHandler<PushEvent>): void;
+	on(event: "before_pr", handler: ExtensionHandler<BeforePrEvent, BeforePrEventResult>): void;
+	on(event: "pr_opened", handler: ExtensionHandler<PrOpenedEvent>): void;
+	on(event: "before_verify", handler: ExtensionHandler<BeforeVerifyEvent, BeforeVerifyEventResult>): void;
+	on(event: "verify_result", handler: ExtensionHandler<VerifyResultEvent>): void;
+	on(event: "budget_threshold", handler: ExtensionHandler<BudgetThresholdEvent, BudgetThresholdEventResult>): void;
+	on(event: "milestone_start", handler: ExtensionHandler<MilestoneStartEvent>): void;
+	on(event: "milestone_end", handler: ExtensionHandler<MilestoneEndEvent>): void;
+	on(event: "unit_start", handler: ExtensionHandler<UnitStartEvent>): void;
+	on(event: "unit_end", handler: ExtensionHandler<UnitEndEvent>): void;
+	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
+	on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent>): void;
+	on(event: "message_start", handler: ExtensionHandler<MessageStartEvent>): void;
+	on(event: "message_update", handler: ExtensionHandler<MessageUpdateEvent>): void;
+	on(event: "message_end", handler: ExtensionHandler<MessageEndEvent>): void;
+	on(event: "tool_execution_start", handler: ExtensionHandler<ToolExecutionStartEvent>): void;
+	on(event: "tool_execution_update", handler: ExtensionHandler<ToolExecutionUpdateEvent>): void;
+	on(event: "tool_execution_end", handler: ExtensionHandler<ToolExecutionEndEvent>): void;
+	on(event: "model_select", handler: ExtensionHandler<ModelSelectEvent>): void;
+	on(event: "bash_transform", handler: ExtensionHandler<BashTransformEvent, BashTransformEventResult>): void;
+	on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
+	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
+	on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;
+	on(event: "input", handler: ExtensionHandler<InputEvent, InputEventResult>): void;
+	on(event: "before_model_select", handler: ExtensionHandler<BeforeModelSelectEvent, BeforeModelSelectResult>): void;
+	on(event: "adjust_tool_set", handler: ExtensionHandler<AdjustToolSetEvent, AdjustToolSetResult>): void;
+
+	// =========================================================================
+	// Event Emission (for host extensions that orchestrate model selection)
+	// =========================================================================
+
+	/** Emit before_model_select event. Returns override model ID or undefined. */
+	emitBeforeModelSelect(event: Omit<BeforeModelSelectEvent, "type">): Promise<BeforeModelSelectResult | undefined>;
+
+	/** Emit adjust_tool_set event (ADR-005). Returns override tool names or undefined. */
+	emitAdjustToolSet(event: Omit<AdjustToolSetEvent, "type">): Promise<AdjustToolSetResult | undefined>;
+
+	/**
+	 * Emit a Layer 2 extension event from an extension. Supports the
+	 * post-plan additions: `notification`, `stop`, `session_end`,
+	 * `before_commit` / `commit`, `before_push` / `push`, `before_pr` /
+	 * `pr_opened`, `before_verify` / `verify_result`, `budget_threshold`,
+	 * `milestone_start` / `milestone_end`, `unit_start` / `unit_end`.
+	 *
+	 * The returned value is the aggregate handler result where meaningful
+	 * (e.g. `{ cancel: true, reason }` from `before_commit`).
+	 */
+	emitExtensionEvent(event: ExtensionEvent): Promise<unknown>;
+
+	// =========================================================================
+	// Tool Registration
+	// =========================================================================
+
+	/** Register a tool that the LLM can call. */
+	registerTool<TParams extends TSchema = TSchema, TDetails = unknown>(tool: ToolDefinition<TParams, TDetails>): void;
+
+	// =========================================================================
+	// Command, Shortcut, Flag Registration
+	// =========================================================================
+
+	/** Register a custom command. */
+	registerCommand(name: string, options: Omit<RegisteredCommand, "name">): void;
+
+	/** Register a lifecycle hook run before package installation starts. */
+	registerBeforeInstall(handler: LifecycleHookHandler): void;
+
+	/** Register a lifecycle hook run after package installation completes. */
+	registerAfterInstall(handler: LifecycleHookHandler): void;
+
+	/** Register a lifecycle hook run before package removal starts. */
+	registerBeforeRemove(handler: LifecycleHookHandler): void;
+
+	/** Register a lifecycle hook run after package removal completes. */
+	registerAfterRemove(handler: LifecycleHookHandler): void;
+
+	/** Register a keyboard shortcut. */
+	registerShortcut(
+		shortcut: KeyId,
+		options: {
+			description?: string;
+			handler: (ctx: ExtensionContext) => Promise<void> | void;
+		},
+	): void;
+
+	/** Register a CLI flag. */
+	registerFlag(
+		name: string,
+		options: {
+			description?: string;
+			type: "boolean" | "string";
+			default?: boolean | string;
+		},
+	): void;
+
+	/** Get the value of a registered CLI flag. */
+	getFlag(name: string): boolean | string | undefined;
+
+	// =========================================================================
+	// Message Rendering
+	// =========================================================================
+
+	/** Register a custom renderer for CustomMessageEntry. */
+	registerMessageRenderer<T = unknown>(customType: string, renderer: MessageRenderer<T>): void;
+
+	// =========================================================================
+	// Actions
+	// =========================================================================
+
+	/** Send a custom message to the session. */
+	sendMessage<T = unknown>(
+		message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,
+		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+	): void;
+
+	/**
+	 * Send a user message to the agent. Always triggers a turn.
+	 * When the agent is streaming, use deliverAs to specify how to queue the message.
+	 */
+	sendUserMessage(
+		content: string | (TextContent | ImageContent)[],
+		options?: { deliverAs?: "steer" | "followUp" },
+	): void;
+
+	/**
+	 * Retry the last turn by removing the failed assistant response and
+	 * re-running the agent from the last user message. No-op if the last
+	 * message is not an assistant error.
+	 */
+	retryLastTurn(): void;
+
+	/** Append a custom entry to the session for state persistence (not sent to LLM). */
+	appendEntry<T = unknown>(customType: string, data?: T): void;
+
+	// =========================================================================
+	// Session Metadata
+	// =========================================================================
+
+	/** Set the session display name (shown in session selector). */
+	setSessionName(name: string): void;
+
+	/** Get the current session name, if set. */
+	getSessionName(): string | undefined;
+
+	/** Set or clear a label on an entry. Labels are user-defined markers for bookmarking/navigation. */
+	setLabel(entryId: string, label: string | undefined): void;
+
+	/** Execute a shell command. */
+	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+
+	/** Get the list of currently active tool names. */
+	getActiveTools(): string[];
+
+	/** Get all configured tools with name and description. */
+	getAllTools(): ToolInfo[];
+
+	/** Set the active tools by name. */
+	setActiveTools(toolNames: string[]): void;
+
+	/**
+	 * Get the prompt-only skill catalog filter, if one is active.
+	 * Undefined means all loaded skills remain visible in <available_skills>.
+	 */
+	getVisibleSkills(): string[] | undefined;
+
+	/**
+	 * Set or clear the prompt-only skill catalog filter.
+	 *
+	 * This changes which loaded skills are advertised in <available_skills>;
+	 * it does not unload skills or disable the Skill tool.
+	 */
+	setVisibleSkills(skillNames: string[] | undefined): void;
+
+	/** Get available slash commands in the current session. */
+	getCommands(): SlashCommandInfo[];
+
+	// =========================================================================
+	// Model and Thinking Level
+	// =========================================================================
+
+	/** Set the current model. Returns false if no API key available. */
+	setModel(model: Model<any>, options?: { persist?: boolean }): Promise<boolean>;
+
+	/** Get current thinking level. */
+	getThinkingLevel(): ThinkingLevel;
+
+	/** Set thinking level (clamped to model capabilities). */
+	setThinkingLevel(level: ThinkingLevel): void;
+
+	// =========================================================================
+	// Provider Registration
+	// =========================================================================
+
+	/**
+	 * Register or override a model provider.
+	 *
+	 * If `models` is provided: replaces all existing models for this provider.
+	 * If only `baseUrl` is provided: overrides the URL for existing models.
+	 * If `oauth` is provided: registers OAuth provider for /login support.
+	 * If `streamSimple` is provided: registers a custom API stream handler.
+	 *
+	 * During initial extension load this call is queued and applied once the
+	 * runner has bound its context. After that it takes effect immediately, so
+	 * it is safe to call from command handlers or event callbacks without
+	 * requiring a `/reload`.
+	 *
+	 * @example
+	 * // Register a new provider with custom models
+	 * pi.registerProvider("my-proxy", {
+	 *   baseUrl: "https://proxy.example.com",
+	 *   apiKey: "PROXY_API_KEY",
+	 *   api: "anthropic-messages",
+	 *   models: [
+	 *     {
+	 *       id: "claude-sonnet-4-20250514",
+	 *       name: "Claude 4 Sonnet (proxy)",
+	 *       reasoning: false,
+	 *       input: ["text", "image"],
+	 *       cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	 *       contextWindow: 200000,
+	 *       maxTokens: 16384
+	 *     }
+	 *   ]
+	 * });
+	 *
+	 * @example
+	 * // Override baseUrl for an existing provider
+	 * pi.registerProvider("anthropic", {
+	 *   baseUrl: "https://proxy.example.com"
+	 * });
+	 *
+	 * @example
+	 * // Register provider with OAuth support
+	 * pi.registerProvider("corporate-ai", {
+	 *   baseUrl: "https://ai.corp.com",
+	 *   api: "openai-responses",
+	 *   models: [...],
+	 *   oauth: {
+	 *     name: "Corporate AI (SSO)",
+	 *     async login(callbacks) { ... },
+	 *     async refreshToken(credentials) { ... },
+	 *     getApiKey(credentials) { return credentials.access; }
+	 *   }
+	 * });
+	 */
+	registerProvider(name: string, config: ProviderConfig): void;
+
+	/**
+	 * Unregister a previously registered provider.
+	 *
+	 * Removes all models belonging to the named provider and restores any
+	 * built-in models that were overridden by it. Has no effect if the provider
+	 * is not currently registered.
+	 *
+	 * Like `registerProvider`, this takes effect immediately when called after
+	 * the initial load phase.
+	 *
+	 * @example
+	 * pi.unregisterProvider("my-proxy");
+	 */
+	unregisterProvider(name: string): void;
+
+	/** Shared event bus for extension communication. */
+	events: EventBus;
+}
+
+// ============================================================================
+// Provider Registration Types
+// ============================================================================
+
+/** Configuration for registering a provider via pi.registerProvider(). */
+export interface ProviderConfig {
+	/** Auth behavior for provider availability and request key handling. Defaults to "apiKey". */
+	authMode?: "apiKey" | "oauth" | "externalCli" | "none";
+	/** Optional readiness check. Return false if the provider cannot accept requests (e.g., CLI not authenticated, API key invalid).
+	 * Called before default auth checks. Trusted at the same level as extension code — extensions already have arbitrary code execution. */
+	isReady?: () => boolean;
+	/** Base URL for the API endpoint. Required when defining models. */
+	baseUrl?: string;
+	/** API key or environment variable name. Required when defining models (unless oauth provided). */
+	apiKey?: string;
+	/** API type. Required at provider or model level when defining models. */
+	api?: Api;
+	/** Optional streamSimple handler for custom APIs. */
+	streamSimple?: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+	/** Custom headers to include in requests. */
+	headers?: Record<string, string>;
+	/** If true, adds Authorization: Bearer header with the resolved API key. */
+	authHeader?: boolean;
+	/** Models to register. If provided, replaces all existing models for this provider. */
+	models?: ProviderModelConfig[];
+	/** OAuth provider for /login support. The `id` is set automatically from the provider name. */
+	oauth?: {
+		/** Display name for the provider in login UI. */
+		name: string;
+		/** Run the login flow, return credentials to persist. */
+		login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+		/** Refresh expired credentials, return updated credentials to persist. */
+		refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+		/** Convert credentials to API key string for the provider. */
+		getApiKey(credentials: OAuthCredentials): string;
+		/** Optional: modify models for this provider (e.g., update baseUrl based on credentials). */
+		modifyModels?(models: Model<Api>[], credentials: OAuthCredentials): Model<Api>[];
+	};
+}
+
+/** Configuration for a model within a provider. */
+export interface ProviderModelConfig {
+	/** Model ID (e.g., "claude-sonnet-4-20250514"). */
+	id: string;
+	/** Display name (e.g., "Claude 4 Sonnet"). */
+	name: string;
+	/** API type override for this model. */
+	api?: Api;
+	/** Whether the model supports extended thinking. */
+	reasoning: boolean;
+	/** Supported input types. */
+	input: ("text" | "image")[];
+	/** Cost per token (for tracking, can be 0). */
+	cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	/** Maximum context window size in tokens. */
+	contextWindow: number;
+	/** Maximum output tokens. */
+	maxTokens: number;
+	/** Custom headers for this model. */
+	headers?: Record<string, string>;
+	/** OpenAI compatibility settings. */
+	compat?: Model<Api>["compat"];
+	/** Opaque provider-specific options (e.g. Ollama keep_alive, num_gpu). */
+	providerOptions?: Record<string, unknown>;
+}
+
+/** Extension factory function type. Supports both sync and async initialization. */
+export type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>;
+
+// ============================================================================
+// Loaded Extension Types
+// ============================================================================
+
+export interface RegisteredTool {
+	definition: ToolDefinition;
+	extensionPath: string;
+}
+
+export interface ExtensionFlag {
+	name: string;
+	description?: string;
+	type: "boolean" | "string";
+	default?: boolean | string;
+	extensionPath: string;
+}
+
+export interface ExtensionShortcut {
+	shortcut: KeyId;
+	description?: string;
+	handler: (ctx: ExtensionContext) => Promise<void> | void;
+	extensionPath: string;
+}
+
+type HandlerFn = (...args: unknown[]) => Promise<unknown>;
+
+/** Tool info with name, description, and parameter schema */
+export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters">;
+
+/**
+ * Shared state created by loader, used during registration and runtime.
+ * Contains flag values (defaults set during registration, CLI values set after).
+ */
+export interface ExtensionRuntimeState {
+	flagValues: Map<string, boolean | string>;
+	/** Provider registrations queued during extension loading, processed when runner binds */
+	pendingProviderRegistrations: Array<{ name: string; config: ProviderConfig }>;
+	/**
+	 * Register or unregister a provider.
+	 *
+	 * Before bindCore(): queues registrations / removes from queue.
+	 * After bindCore(): calls ModelRegistry directly for immediate effect.
+	 */
+	registerProvider: (name: string, config: ProviderConfig) => void;
+	unregisterProvider: (name: string) => void;
+	/** Emit before_model_select event to all registered handlers. Bound by ExtensionRunner. */
+	emitBeforeModelSelect: (event: Omit<BeforeModelSelectEvent, "type">) => Promise<BeforeModelSelectResult | undefined>;
+	/** Emit adjust_tool_set event to all registered handlers. Bound by ExtensionRunner (ADR-005). */
+	emitAdjustToolSet: (event: Omit<AdjustToolSetEvent, "type">) => Promise<AdjustToolSetResult | undefined>;
+	/**
+	 * Emit a Layer 2 extension event from an extension. Supports the
+	 * post-plan additions (notification, stop, git lifecycle, verify,
+	 * budget, milestone, unit, session_end). Returns the handler chain's
+	 * aggregate result for events that support vetoes / mutations.
+	 */
+	emitExtensionEvent: (event: ExtensionEvent) => Promise<unknown>;
+}
+
+/**
+ * Action implementations for pi.* API methods.
+ * Provided to runner.initialize(), copied into the shared runtime.
+ */
+export interface ExtensionActions {
+	sendMessage: <T = unknown>(
+		message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,
+		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+	) => void;
+	sendUserMessage: (
+		content: string | (TextContent | ImageContent)[],
+		options?: { deliverAs?: "steer" | "followUp" },
+	) => void;
+	retryLastTurn: () => void;
+	appendEntry: <T = unknown>(customType: string, data?: T) => void;
+	setSessionName: (name: string) => void;
+	getSessionName: () => string | undefined;
+	setLabel: (entryId: string, label: string | undefined) => void;
+	getActiveTools: () => string[];
+	getAllTools: () => ToolInfo[];
+	setActiveTools: (toolNames: string[]) => void;
+	getVisibleSkills: () => string[] | undefined;
+	setVisibleSkills: (skillNames: string[] | undefined) => void;
+	refreshTools: () => void;
+	getCommands: () => SlashCommandInfo[];
+	setModel: (model: Model<any>, options?: { persist?: boolean }) => Promise<boolean>;
+	getThinkingLevel: () => ThinkingLevel;
+	setThinkingLevel: (level: ThinkingLevel) => void;
+}
+
+/**
+ * Actions for ExtensionContext (ctx.* in event handlers).
+ * Required by all modes.
+ */
+export interface ExtensionContextActions {
+	getModel: () => Model<any> | undefined;
+	isIdle: () => boolean;
+	abort: () => void;
+	hasPendingMessages: () => boolean;
+	shutdown: () => void;
+	getContextUsage: () => ContextUsage | undefined;
+	compact: (options?: CompactOptions) => void;
+	getSystemPrompt: () => string;
+	setCompactionThresholdOverride: (percent: number | undefined) => void;
+}
+
+/**
+ * Actions for ExtensionCommandContext (ctx.* in command handlers).
+ * Only needed for interactive mode where extension commands are invokable.
+ */
+export interface ExtensionCommandContextActions {
+	waitForIdle: () => Promise<void>;
+	newSession: (options?: {
+		parentSession?: string;
+		setup?: (sessionManager: SessionManager) => Promise<void>;
+		/** See ExtensionCommandContext.newSession for docs. */
+		workspaceRoot?: string;
+		/** See ExtensionCommandContext.newSession for docs (#3731). */
+		abortSignal?: AbortSignal;
+	}) => Promise<{ cancelled: boolean }>;
+	fork: (entryId: string) => Promise<{ cancelled: boolean }>;
+	navigateTree: (
+		targetId: string,
+		options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string },
+	) => Promise<{ cancelled: boolean }>;
+	switchSession: (sessionPath: string) => Promise<{ cancelled: boolean }>;
+	reload: () => Promise<void>;
+}
+
+/**
+ * Full runtime = state + actions.
+ * Created by loader with throwing action stubs, completed by runner.initialize().
+ */
+export interface ExtensionRuntime extends ExtensionRuntimeState, ExtensionActions {}
+
+/** Loaded extension with all registered items. */
+export interface Extension {
+	path: string;
+	resolvedPath: string;
+	handlers: Map<string, HandlerFn[]>;
+	tools: Map<string, RegisteredTool>;
+	messageRenderers: Map<string, MessageRenderer>;
+	commands: Map<string, RegisteredCommand>;
+	flags: Map<string, ExtensionFlag>;
+	shortcuts: Map<KeyId, ExtensionShortcut>;
+	lifecycleHooks: LifecycleHookMap;
+}
+
+/** Warning from extension dependency sort (missing deps, cycles). */
+export interface ExtensionLoadWarning {
+	declaringId: string;
+	missingId: string;
+	message: string;
+}
+
+/** Result of loading extensions. */
+export interface LoadExtensionsResult {
+	extensions: Extension[];
+	errors: Array<{ path: string; error: string }>;
+	warnings: ExtensionLoadWarning[];
+	/** Shared runtime - actions are throwing stubs until runner.initialize() */
+	runtime: ExtensionRuntime;
+}
+
+// ============================================================================
+// Extension Error
+// ============================================================================
+
+export interface ExtensionError {
+	extensionPath: string;
+	event: string;
+	error: string;
+	stack?: string;
+}