@oh-my-pi/pi-coding-agent 15.5.11 → 15.5.12

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [15.5.12] - 2026-05-29
+
+### Added
+
+- Added the `omp-plugins` discovery provider, which scans every extension package directory configured via `extensions:` (in `~/.omp/agent/settings.json` or `<cwd>/.omp/settings.json`) or `--extension`/`-e` on the CLI for `skills/`, `hooks/pre|post/`, `tools/`, `commands/`, `rules/`, `prompts/`, and `.mcp.json`. Prior to this, only the extension's TypeScript factory module ran; every sibling capability the docs (https://omp.sh/docs/extension-authoring) advertised was silently ignored ([#1496](https://github.com/can1357/oh-my-pi/issues/1496)).
+- Added the top-level `omp install <target>` subcommand documented at https://omp.sh/docs/extension-authoring. Local paths route to `omp plugin link` (so the directory is symlinked into the plugin set), and npm/marketplace specs route to `omp plugin install`. Before this, `install` was not a registered subcommand and the CLI runner silently forwarded `install ./my-extension` to `launch` as an initial LLM prompt ([#1496](https://github.com/can1357/oh-my-pi/issues/1496)).
+
+### Changed
+
+- Changed the sticky `Todos` panel above the editor to advance as tasks close, instead of pinning to the first 5 tasks of the active phase. `selectStickyTodoWindow` now shows up to 5 open (pending / in_progress) tasks in original phase order and reports the count of remaining open tasks for the `+N more` hint, so every `todo_write` flip produces a visible row shift. Closed-phase tail falls back to the last 5 tasks (with the `+N more` line suppressed) until `getActivePhase` walks to the next phase.
+- Linked the sticky `Todos` panel to the live `SessionObserverRegistry` so pending todos that have an in-flight subagent doing their work light up green with an animated spinner — the same `theme.spinnerFrames` ("status" preset) the `task` tool uses for its agent rows — instead of staying greyed out as if nothing is happening. A new exported `todoMatchesAnyDescription(content, descriptions)` does case- and whitespace-insensitive equality first with a 6-char minimum-overlap substring fallback in either direction, so "Sonnet #2: shallow bug scan" and a subagent description of "Sonnet #2" still link up. Completed todos now render with `theme.status.success` (✔ / `\uf00c` / `[ok]` per symbol preset, still wrapped in the `success` colour so themed palettes can keep their purple/green/whatever) and in_progress rows render with `theme.status.running`, matching the `task` tool's icon vocabulary. The spinner interval only ticks while at least one visible open todo has a matched active subagent, and self-stops once subagents finish, so plain in_progress todos do not animate forever in the absence of subagent activity.
+- Extracted the top-level CLI command table from `src/cli.ts` into a side-effect-free `src/cli-commands.ts` so test code can introspect the registered subcommands without triggering the entrypoint's top-level await.
+
 ## [15.5.11] - 2026-05-29
 
 ### Added

package/dist/types/cli-commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Top-level CLI command table.
+ *
+ * Lives in its own module (importable without side effects) so that tests can
+ * inspect the registered subcommands without triggering the side-effectful
+ * top-level await in `cli.ts`. Adding a new subcommand here is enough to make
+ * `runCli` route to it instead of forwarding the argv as a prompt to
+ * `launch` — see #1496 for the original "args silently leak to the LLM"
+ * regression that motivated the split.
+ */
+import type { CommandEntry } from "@oh-my-pi/pi-utils/cli";
+export declare const commands: CommandEntry[];
+/**
+ * Return true when `first` matches a registered subcommand name or alias.
+ *
+ * Flags (`-…`) and `@file` arguments are never subcommands; for those the CLI
+ * runner skips ahead to the default `launch` command.
+ */
+export declare function isSubcommand(first: string | undefined): boolean;

package/dist/types/commands/install.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `omp install <target>` — top-level convenience over `omp plugin install` /
+ * `omp plugin link`.
+ *
+ * The docs (omp.sh/docs/extension-authoring) advertise
+ *
+ *   omp install ./my-extension
+ *
+ * as a third loading mechanism that "symlinks the directory into the plugin
+ * set and watches it for changes". Before this command existed, `install` was
+ * not a registered subcommand, so the CLI runner forwarded the argv to the
+ * default `launch` command and the model received `install ./my-extension`
+ * as an initial prompt — see #1496.
+ *
+ * Local-path targets (`./foo`, `/abs/foo`, `~/foo`, or an existing directory)
+ * route to `plugin link` so they are symlinked into the plugin set, matching
+ * the documented behavior. Everything else (`pkg`, `pkg@1.2.3`,
+ * `name@marketplace`) routes to `plugin install`.
+ */
+import { Command } from "@oh-my-pi/pi-utils/cli";
+/**
+ * Heuristic used to decide whether `omp install <target>` should `link` a
+ * local directory or `install` a remote spec. Exported for tests.
+ */
+export declare function looksLikeLocalPath(target: string): boolean;
+export default class Install extends Command {
+    static description: string;
+    static args: {
+        targets: import("@oh-my-pi/pi-utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+            multiple: true;
+        };
+    };
+    static flags: {
+        json: import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        force: import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        "dry-run": import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        scope: import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            options: string[];
+        };
+    };
+    run(): Promise<void>;
+}

package/dist/types/discovery/index.d.ts

@@ -30,6 +30,7 @@ import "./gemini";
 import "./opencode";
 import "./github";
 import "./mcp-json";
+import "./omp-plugins";
 import "./ssh";
 import "./vscode";
 import "./windsurf";

package/dist/types/discovery/omp-extension-roots.d.ts

@@ -0,0 +1,43 @@
+import type { LoadContext } from "../capability/types";
+/** A resolved extension package directory wired into the discovery surfaces. */
+export interface OmpExtensionRoot {
+    /** Absolute path to the package directory. */
+    path: string;
+    /** Stable display name (basename of the package directory). */
+    name: string;
+    /** Scope from which the path was sourced. */
+    level: "user" | "project";
+}
+/**
+ * Register CLI-provided extension package paths (e.g. from `--extension`/`-e`)
+ * so the sub-discovery providers can find their sibling `skills/`, `hooks/`,
+ * etc. Paths that do not resolve to a directory are silently dropped — file
+ * entrypoints have no package sub-tree to scan.
+ *
+ * Call once during startup before any capability load. Repeated calls extend
+ * the registered set; {@link clearOmpExtensionCliRoots} resets for tests.
+ */
+export declare function injectOmpExtensionCliRoots(paths: readonly string[], home: string, cwd: string): void;
+/** Drop every CLI-injected root. Tests use this between cases. */
+export declare function clearOmpExtensionCliRoots(): void;
+/** Inspect currently-injected CLI roots (read-only). Exposed for diagnostics + tests. */
+export declare function getInjectedOmpExtensionCliRoots(): readonly OmpExtensionRoot[];
+/**
+ * Resolve every configured extension package directory for the given context.
+ *
+ * Sources, in order of precedence (later entries with the same absolute path
+ * are dropped):
+ *
+ * 1. CLI roots injected via {@link injectOmpExtensionCliRoots}
+ * 2. Project `<cwd>/.omp/settings.json#extensions`
+ * 3. User `~/.omp/agent/settings.json#extensions`
+ * 4. Enabled plugins installed under `<plugins>/node_modules/` (e.g. via
+ *    `omp install <pkg>` / `omp plugin install` / `omp plugin link`)
+ *
+ * Only entries that resolve to a directory on disk are returned; file
+ * entrypoints contribute zero sub-discovery surface and are filtered out.
+ * Installed-plugin enumeration failures (missing lockfile, unreadable
+ * `package.json`, etc.) are logged at `debug` and degrade gracefully — the
+ * other sources still surface.
+ */
+export declare function listOmpExtensionRoots(ctx: LoadContext): Promise<OmpExtensionRoot[]>;

package/dist/types/discovery/omp-plugins.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/extensibility/plugins/loader.d.ts

@@ -1,9 +1,19 @@
 import type { InstalledPlugin } from "./types";
 /**
  * Get list of enabled plugins with their resolved configurations.
- * Respects both global runtime config and project overrides.
+ *
+ * Respects both global runtime config and project overrides. Iterates the
+ * union of `<plugins>/package.json#dependencies` (`bun install`-installed
+ * packages) and `<plugins>/omp-plugins.lock.json#plugins` (so locally
+ * `plugin link`-symlinked extensions, which never get a dependency entry,
+ * are still discovered). The optional `home` parameter pins the plugins
+ * root for callers that need to enumerate plugins relative to a non-default
+ * home (tests with a tempdir, discovery loaders threaded with
+ * `LoadContext.home`).
  */
-export declare function getEnabledPlugins(cwd: string): Promise<InstalledPlugin[]>;
+export declare function getEnabledPlugins(cwd: string, opts?: {
+    home?: string;
+}): Promise<InstalledPlugin[]>;
 export declare function resolvePluginToolPaths(plugin: InstalledPlugin): string[];
 export declare function resolvePluginHookPaths(plugin: InstalledPlugin): string[];
 export declare function resolvePluginCommandPaths(plugin: InstalledPlugin): string[];

package/dist/types/tools/todo-write.d.ts

@@ -49,6 +49,36 @@ declare const todoWriteSchema: z.ZodObject<{
 type TodoWriteParams = z.infer<typeof todoWriteSchema>;
 export declare const USER_TODO_EDIT_CUSTOM_TYPE = "user_todo_edit";
 export declare function getLatestTodoPhasesFromEntries(entries: SessionEntry[]): TodoPhase[];
+/**
+ * Pick the actionable window of tasks to display in the sticky todo panel.
+ *
+ * Returns up to `maxVisible` open (pending / in_progress) tasks in their
+ * original phase order, plus the count of remaining open tasks not shown so
+ * the caller can render a `+N more` hint. When every task in `tasks` is
+ * closed (completed or abandoned), returns the trailing `maxVisible` tasks
+ * with `hiddenOpenCount = 0`, so the panel keeps useful context until the
+ * active-phase pointer advances on the next `todo_write`.
+ *
+ * Task identity and order are preserved — this is a slice, never a sort.
+ */
+export declare function selectStickyTodoWindow(tasks: TodoItem[], maxVisible?: number): {
+    visible: TodoItem[];
+    hiddenOpenCount: number;
+};
+/**
+ * Report whether `content` likely names the same work as any entry in
+ * `descriptions`. Used by the sticky todo panel to light up a pending todo
+ * when an in-flight subagent is doing the work for it, without requiring
+ * the caller to flip the todo's status.
+ *
+ * Matching is normalize-then-equal first (lowercased; punctuation and
+ * whitespace runs both collapsed to a single space; trimmed), with a
+ * substring fallback in either direction so minor wording drift
+ * ("Sonnet #2: bug scan" vs "Sonnet #2") still links up. The substring
+ * fallback requires at least {@link TODO_DESCRIPTION_MIN_OVERLAP} chars on
+ * the contained side.
+ */
+export declare function todoMatchesAnyDescription(content: string, descriptions: readonly string[]): boolean;
 /** Apply an array of `todo_write`-style ops to existing phases. Used by /todo slash command. */
 export declare function applyOpsToPhases(currentPhases: TodoPhase[], ops: TodoWriteParams["ops"]): {
     phases: TodoPhase[];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "15.5.11",
+	"version": "15.5.12",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -47,13 +47,13 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "15.5.11",
-		"@oh-my-pi/omp-stats": "15.5.11",
-		"@oh-my-pi/pi-agent-core": "15.5.11",
-		"@oh-my-pi/pi-ai": "15.5.11",
-		"@oh-my-pi/pi-natives": "15.5.11",
-		"@oh-my-pi/pi-tui": "15.5.11",
-		"@oh-my-pi/pi-utils": "15.5.11",
+		"@oh-my-pi/hashline": "15.5.12",
+		"@oh-my-pi/omp-stats": "15.5.12",
+		"@oh-my-pi/pi-agent-core": "15.5.12",
+		"@oh-my-pi/pi-ai": "15.5.12",
+		"@oh-my-pi/pi-natives": "15.5.12",
+		"@oh-my-pi/pi-tui": "15.5.12",
+		"@oh-my-pi/pi-utils": "15.5.12",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/cli-commands.ts

@@ -0,0 +1,44 @@
+/**
+ * Top-level CLI command table.
+ *
+ * Lives in its own module (importable without side effects) so that tests can
+ * inspect the registered subcommands without triggering the side-effectful
+ * top-level await in `cli.ts`. Adding a new subcommand here is enough to make
+ * `runCli` route to it instead of forwarding the argv as a prompt to
+ * `launch` — see #1496 for the original "args silently leak to the LLM"
+ * regression that motivated the split.
+ */
+import type { CommandEntry } from "@oh-my-pi/pi-utils/cli";
+
+export const commands: CommandEntry[] = [
+	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
+	{ name: "acp", load: () => import("./commands/acp").then(m => m.default) },
+	{ name: "auth-broker", load: () => import("./commands/auth-broker").then(m => m.default) },
+	{ name: "auth-gateway", load: () => import("./commands/auth-gateway").then(m => m.default) },
+	{ name: "agents", load: () => import("./commands/agents").then(m => m.default) },
+	{ name: "commit", load: () => import("./commands/commit").then(m => m.default) },
+	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
+	{ name: "grep", load: () => import("./commands/grep").then(m => m.default) },
+	{ name: "grievances", load: () => import("./commands/grievances").then(m => m.default) },
+	{ name: "install", load: () => import("./commands/install").then(m => m.default) },
+	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
+	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
+	{ name: "shell", load: () => import("./commands/shell").then(m => m.default) },
+	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
+	{ name: "ssh", load: () => import("./commands/ssh").then(m => m.default) },
+	{ name: "stats", load: () => import("./commands/stats").then(m => m.default) },
+	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
+	{ name: "worktree", load: () => import("./commands/worktree").then(m => m.default), aliases: ["wt"] },
+	{ name: "search", load: () => import("./commands/web-search").then(m => m.default), aliases: ["q"] },
+];
+
+/**
+ * Return true when `first` matches a registered subcommand name or alias.
+ *
+ * Flags (`-…`) and `@file` arguments are never subcommands; for those the CLI
+ * runner skips ahead to the default `launch` command.
+ */
+export function isSubcommand(first: string | undefined): boolean {
+	if (!first || first.startsWith("-") || first.startsWith("@")) return false;
+	return commands.some(entry => entry.name === first || entry.aliases?.includes(first));
+}

package/src/cli.ts

@@ -10,7 +10,8 @@ procmgr.scrubProcessEnv();
  * CLI entry point — registers all commands explicitly and delegates to the
  * lightweight CLI runner from pi-utils.
  */
-import { type CliConfig, type CommandEntry, run } from "@oh-my-pi/pi-utils/cli";
+import { type CliConfig, run } from "@oh-my-pi/pi-utils/cli";
+import { commands, isSubcommand } from "./cli-commands";
 
 if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 	process.stderr.write(
@@ -21,27 +22,6 @@ if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 
 process.title = APP_NAME;
 
-const commands: CommandEntry[] = [
-	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
-	{ name: "acp", load: () => import("./commands/acp").then(m => m.default) },
-	{ name: "auth-broker", load: () => import("./commands/auth-broker").then(m => m.default) },
-	{ name: "auth-gateway", load: () => import("./commands/auth-gateway").then(m => m.default) },
-	{ name: "agents", load: () => import("./commands/agents").then(m => m.default) },
-	{ name: "commit", load: () => import("./commands/commit").then(m => m.default) },
-	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
-	{ name: "grep", load: () => import("./commands/grep").then(m => m.default) },
-	{ name: "grievances", load: () => import("./commands/grievances").then(m => m.default) },
-	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
-	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
-	{ name: "shell", load: () => import("./commands/shell").then(m => m.default) },
-	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
-	{ name: "ssh", load: () => import("./commands/ssh").then(m => m.default) },
-	{ name: "stats", load: () => import("./commands/stats").then(m => m.default) },
-	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
-	{ name: "worktree", load: () => import("./commands/worktree").then(m => m.default), aliases: ["wt"] },
-	{ name: "search", load: () => import("./commands/web-search").then(m => m.default), aliases: ["q"] },
-];
-
 async function showHelp(config: CliConfig): Promise<void> {
 	const { renderRootHelp } = await import("@oh-my-pi/pi-utils/cli");
 	const { getExtraHelpText } = await import("./cli/args");
@@ -51,16 +31,6 @@ async function showHelp(config: CliConfig): Promise<void> {
 		process.stdout.write(`\n${extra}\n`);
 	}
 }
-
-/**
- * Determine whether argv[0] is a known subcommand name.
- * If not, the entire argv is treated as args to the default "launch" command.
- */
-function isSubcommand(first: string | undefined): boolean {
-	if (!first || first.startsWith("-") || first.startsWith("@")) return false;
-	return commands.some(e => e.name === first || e.aliases?.includes(first));
-}
-
 /**
  * Smoke-test entry. Spawns the stats sync worker, pings it, exits.
  *

package/src/commands/install.ts

@@ -0,0 +1,107 @@
+/**
+ * `omp install <target>` — top-level convenience over `omp plugin install` /
+ * `omp plugin link`.
+ *
+ * The docs (omp.sh/docs/extension-authoring) advertise
+ *
+ *   omp install ./my-extension
+ *
+ * as a third loading mechanism that "symlinks the directory into the plugin
+ * set and watches it for changes". Before this command existed, `install` was
+ * not a registered subcommand, so the CLI runner forwarded the argv to the
+ * default `launch` command and the model received `install ./my-extension`
+ * as an initial prompt — see #1496.
+ *
+ * Local-path targets (`./foo`, `/abs/foo`, `~/foo`, or an existing directory)
+ * route to `plugin link` so they are symlinked into the plugin set, matching
+ * the documented behavior. Everything else (`pkg`, `pkg@1.2.3`,
+ * `name@marketplace`) routes to `plugin install`.
+ */
+
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { type PluginAction, type PluginCommandArgs, runPluginCommand } from "../cli/plugin-cli";
+import { initTheme } from "../modes/theme/theme";
+
+/**
+ * Heuristic used to decide whether `omp install <target>` should `link` a
+ * local directory or `install` a remote spec. Exported for tests.
+ */
+export function looksLikeLocalPath(target: string): boolean {
+	if (target.startsWith(".") || target.startsWith("/") || target.startsWith("~")) return true;
+	// Windows drive prefix (e.g. `C:\foo`).
+	if (/^[a-zA-Z]:[\\/]/.test(target)) return true;
+	// Bare names that happen to exist as a local directory.
+	try {
+		return existsSync(path.resolve(target));
+	} catch {
+		return false;
+	}
+}
+
+export default class Install extends Command {
+	static description = "Install or link an extension package (alias of `plugin install`/`plugin link`)";
+
+	static args = {
+		targets: Args.string({
+			description: "Local path, npm spec, or marketplace ref (e.g. ./my-ext, my-pkg@1.2.3, name@marketplace)",
+			required: false,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON" }),
+		force: Flags.boolean({ description: "Force install" }),
+		"dry-run": Flags.boolean({ description: "Show actions without applying changes" }),
+		scope: Flags.string({
+			description: 'Install scope: "user" (default) or "project" (marketplace installs only)',
+			options: ["user", "project"],
+		}),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Install);
+		const targets = Array.isArray(args.targets) ? args.targets : args.targets ? [args.targets] : [];
+
+		if (targets.length === 0) {
+			process.stderr.write("Usage: omp install <path | npm-spec | name@marketplace> [...]\n");
+			process.exit(1);
+		}
+
+		await initTheme();
+
+		// Split into local-paths (→ link) and remote specs (→ install). Each batch
+		// preserves user-supplied order so progress output reads naturally.
+		const localPaths: string[] = [];
+		const remoteSpecs: string[] = [];
+		for (const target of targets) {
+			if (looksLikeLocalPath(target)) localPaths.push(target);
+			else remoteSpecs.push(target);
+		}
+
+		const baseFlags: PluginCommandArgs["flags"] = {
+			json: flags.json,
+			force: flags.force,
+			dryRun: flags["dry-run"],
+			scope: flags.scope as "user" | "project" | undefined,
+		};
+
+		for (const localPath of localPaths) {
+			await runPluginCommand({
+				action: "link" satisfies PluginAction,
+				args: [localPath],
+				flags: baseFlags,
+			});
+		}
+
+		if (remoteSpecs.length > 0) {
+			await runPluginCommand({
+				action: "install" satisfies PluginAction,
+				args: remoteSpecs,
+				flags: baseFlags,
+			});
+		}
+	}
+}

package/src/discovery/index.ts

@@ -32,6 +32,7 @@ import "./gemini";
 import "./opencode";
 import "./github";
 import "./mcp-json";
+import "./omp-plugins";
 import "./ssh";
 import "./vscode";
 import "./windsurf";

package/src/discovery/omp-extension-roots.ts

@@ -0,0 +1,190 @@
+/**
+ * OMP extension package roots.
+ *
+ * An "extension package root" is a directory configured via either
+ * `extensions:` in user/project settings or the `--extension`/`-e` CLI flag
+ * that points to a packaged extension on disk. The package's standard
+ * sub-directories (`skills/`, `hooks/`, `tools/`, `commands/`, `rules/`,
+ * `prompts/`, `.mcp.json`) are wired into discovery by `omp-plugins.ts`.
+ *
+ * CLI-provided paths are injected via {@link injectOmpExtensionCliRoots}
+ * before discovery runs; settings paths are read lazily from
+ * `<scope>/settings.json` in {@link listOmpExtensionRoots} to mirror what
+ * `loadExtensionModules` already does.
+ *
+ * @see ./omp-plugins.ts
+ * @see ./builtin.ts `loadExtensionModules`
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent, logger, tryParseJson } from "@oh-my-pi/pi-utils";
+import { readDirEntries, readFile } from "../capability/fs";
+import type { LoadContext } from "../capability/types";
+import { getEnabledPlugins } from "../extensibility/plugins/loader";
+import { expandTilde } from "../tools/path-utils";
+
+/** A resolved extension package directory wired into the discovery surfaces. */
+export interface OmpExtensionRoot {
+	/** Absolute path to the package directory. */
+	path: string;
+	/** Stable display name (basename of the package directory). */
+	name: string;
+	/** Scope from which the path was sourced. */
+	level: "user" | "project";
+}
+
+interface InjectedRoot {
+	path: string;
+	level: "user" | "project";
+}
+
+let injectedCliRoots: InjectedRoot[] = [];
+
+/**
+ * Register CLI-provided extension package paths (e.g. from `--extension`/`-e`)
+ * so the sub-discovery providers can find their sibling `skills/`, `hooks/`,
+ * etc. Paths that do not resolve to a directory are silently dropped — file
+ * entrypoints have no package sub-tree to scan.
+ *
+ * Call once during startup before any capability load. Repeated calls extend
+ * the registered set; {@link clearOmpExtensionCliRoots} resets for tests.
+ */
+export function injectOmpExtensionCliRoots(paths: readonly string[], home: string, cwd: string): void {
+	if (paths.length === 0) return;
+	const expanded = paths.map(raw => {
+		const tilde = expandTilde(raw, home);
+		return path.isAbsolute(tilde) ? tilde : path.resolve(cwd, tilde);
+	});
+	const merged = new Map<string, InjectedRoot>();
+	for (const root of injectedCliRoots) merged.set(root.path, root);
+	for (const resolved of expanded) {
+		// CLI scope mirrors how `--extension` is treated elsewhere — user-level overrides win.
+		if (!merged.has(resolved)) merged.set(resolved, { path: resolved, level: "user" });
+	}
+	injectedCliRoots = [...merged.values()];
+}
+
+/** Drop every CLI-injected root. Tests use this between cases. */
+export function clearOmpExtensionCliRoots(): void {
+	injectedCliRoots = [];
+}
+
+/** Inspect currently-injected CLI roots (read-only). Exposed for diagnostics + tests. */
+export function getInjectedOmpExtensionCliRoots(): readonly OmpExtensionRoot[] {
+	return injectedCliRoots.map(({ path: p, level }) => ({ path: p, level, name: path.basename(p) }));
+}
+
+interface ScopeDirs {
+	project: string;
+	user: string;
+}
+
+function scopeDirs(ctx: LoadContext): ScopeDirs {
+	return {
+		project: path.join(ctx.cwd, ".omp"),
+		user: path.join(ctx.home, ".omp", "agent"),
+	};
+}
+
+async function readSettingsExtensions(settingsPath: string): Promise<string[]> {
+	const content = await readFile(settingsPath);
+	if (!content) return [];
+	const parsed = tryParseJson<{ extensions?: unknown }>(content);
+	const raw = parsed?.extensions;
+	if (!Array.isArray(raw)) return [];
+	return raw.filter((entry): entry is string => typeof entry === "string" && entry.length > 0);
+}
+
+function resolveAgainst(raw: string, ctx: LoadContext): string {
+	const tilde = expandTilde(raw, ctx.home);
+	return path.isAbsolute(tilde) ? tilde : path.resolve(ctx.cwd, tilde);
+}
+
+async function isDirectory(p: string): Promise<boolean> {
+	const entries = await readDirEntries(p);
+	if (entries.length > 0) return true;
+	// Empty directory still counts; cache returns [] for both empty and missing.
+	// Disambiguate with a single stat — only hit when the cached listing is empty.
+	try {
+		const stat = await fs.stat(p);
+		return stat.isDirectory();
+	} catch (err) {
+		if (isEnoent(err)) return false;
+		throw err;
+	}
+}
+
+/**
+ * Resolve every configured extension package directory for the given context.
+ *
+ * Sources, in order of precedence (later entries with the same absolute path
+ * are dropped):
+ *
+ * 1. CLI roots injected via {@link injectOmpExtensionCliRoots}
+ * 2. Project `<cwd>/.omp/settings.json#extensions`
+ * 3. User `~/.omp/agent/settings.json#extensions`
+ * 4. Enabled plugins installed under `<plugins>/node_modules/` (e.g. via
+ *    `omp install <pkg>` / `omp plugin install` / `omp plugin link`)
+ *
+ * Only entries that resolve to a directory on disk are returned; file
+ * entrypoints contribute zero sub-discovery surface and are filtered out.
+ * Installed-plugin enumeration failures (missing lockfile, unreadable
+ * `package.json`, etc.) are logged at `debug` and degrade gracefully — the
+ * other sources still surface.
+ */
+export async function listOmpExtensionRoots(ctx: LoadContext): Promise<OmpExtensionRoot[]> {
+	const { project, user } = scopeDirs(ctx);
+	const [projectExtensions, userExtensions, installedPlugins] = await Promise.all([
+		readSettingsExtensions(path.join(project, "settings.json")),
+		readSettingsExtensions(path.join(user, "settings.json")),
+		listInstalledPluginRoots(ctx),
+	]);
+
+	const candidates: InjectedRoot[] = [
+		...injectedCliRoots,
+		...projectExtensions.map((raw): InjectedRoot => ({ path: resolveAgainst(raw, ctx), level: "project" })),
+		...userExtensions.map((raw): InjectedRoot => ({ path: resolveAgainst(raw, ctx), level: "user" })),
+		...installedPlugins,
+	];
+
+	// First-seen-wins dedup preserves CLI > project-settings > user-settings > installed precedence.
+	const seen = new Set<string>();
+	const unique: InjectedRoot[] = [];
+	for (const candidate of candidates) {
+		if (seen.has(candidate.path)) continue;
+		seen.add(candidate.path);
+		unique.push(candidate);
+	}
+
+	const directoryFlags = await Promise.all(unique.map(c => isDirectory(c.path)));
+	const roots: OmpExtensionRoot[] = [];
+	for (let i = 0; i < unique.length; i++) {
+		if (!directoryFlags[i]) continue;
+		const { path: p, level } = unique[i];
+		roots.push({ path: p, level, name: path.basename(p) });
+	}
+	return roots;
+}
+
+/**
+ * Enumerate every enabled installed plugin's package directory so its
+ * conventional `skills/`, `hooks/`, `tools/`, `commands/`, `rules/`,
+ * `prompts/`, and `.mcp.json` are wired into discovery — mirrors how
+ * `getAllPluginExtensionPaths` already feeds the extension factory loader.
+ *
+ * Marketplace and `omp plugin link` installs write to the plugin manager's
+ * `node_modules` (or symlink into it) rather than to `extensions:` in
+ * settings; without this branch the sub-discovery provider would still miss
+ * everything those install paths produce.
+ */
+async function listInstalledPluginRoots(ctx: LoadContext): Promise<InjectedRoot[]> {
+	try {
+		const plugins = await getEnabledPlugins(ctx.cwd, { home: ctx.home });
+		// Installed plugins are always user-scope; project disablement is already
+		// honored by `getEnabledPlugins` via `loadProjectOverrides`.
+		return plugins.map(({ path: p }) => ({ path: p, level: "user" }));
+	} catch (err) {
+		logger.debug("listInstalledPluginRoots: enumeration failed", { error: String(err) });
+		return [];
+	}
+}