@phnx-labs/agents-cli 1.20.12 → 1.20.14

package/dist/lib/exec.js

@@ -34,6 +34,36 @@ export function normalizeMode(input) {
         return v;
     throw new Error(`Invalid mode '${input}'. Use one of: ${ALL_MODES.join(', ')} (or 'full' as a deprecated alias for 'skip').`);
 }
+/**
+ * Detect the headless-plan stall footgun.
+ *
+ * A slash command (e.g. `/code:commit`) run headless under the IMPLICIT default
+ * `plan` mode hangs forever: plan is read-only, so the agent calls ExitPlanMode
+ * to start working, and in a headless run there is no TTY to approve it. The
+ * process just sits there. Callers use this to fail fast with a fix instead.
+ *
+ * Returns the offending command token (e.g. `/code:commit`) when the run should
+ * be blocked, else null. Guards are deliberately narrow:
+ *   - interactive runs / no prompt        -> not headless, never blocks
+ *   - explicit --mode (modeIsDefault false) -> respected; `--mode plan` is a
+ *     legitimate read-only command run and must not be blocked
+ *   - resolved mode is not `plan`          -> only plan stalls at ExitPlanMode
+ *   - prompt is not a slash command        -> natural-language read-only prompts
+ *     ("summarize commits") are a valid default-plan use and must not be blocked
+ */
+export function headlessPlanStallCommand(args) {
+    const { prompt, interactive, mode, modeIsDefault } = args;
+    if (interactive === true || prompt === undefined)
+        return null;
+    if (!modeIsDefault)
+        return null;
+    if (normalizeMode(mode) !== 'plan')
+        return null;
+    const trimmed = prompt.trimStart();
+    if (!trimmed.startsWith('/'))
+        return null;
+    return trimmed.split(/\s+/)[0];
+}
 /**
  * Resolve a requested mode against an agent's capability table.
  *
@@ -71,6 +101,19 @@ export function resolveMode(agent, requested) {
 export function defaultModeFor(agent) {
     return AGENTS[agent].capabilities.modes[0];
 }
+/**
+ * Resolve interactive vs headless. Explicit flags are definitive and win over
+ * inference: `--interactive` forces interactive, `--headless` forces headless.
+ * With neither flag, prompt presence decides (prompt -> headless, none -> interactive).
+ * `--interactive` takes precedence over `--headless`; the CLI layer rejects passing both.
+ */
+export function resolveInteractive(options) {
+    if (options.interactive === true)
+        return true;
+    if (options.headless === true)
+        return false;
+    return options.prompt === undefined;
+}
 /** Pattern for valid environment variable names (C identifier rules). */
 const EXEC_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Parse a single KEY=VALUE string into a tuple, validating the key name. */
@@ -352,16 +395,40 @@ export const AGENT_COMMANDS = {
         jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
     },
+    // Factory AI Droid (`droid exec` for headless, `droid` for TUI). Flags from
+    // docs.factory.ai CLI reference: prompt is positional; --auto low|medium|high
+    // escalates autonomy (default is read-only); --skip-permissions-unsafe drops
+    // all guardrails; -o stream-json streams JSONL events; -m selects the model.
+    // The `exec` subcommand is dropped for interactive runs (see buildExecCommand).
+    droid: {
+        base: ['droid', 'exec'],
+        promptFlag: 'positional',
+        modeFlags: {
+            plan: [], // droid's default exec mode is read-only
+            edit: ['--auto', 'low'], // create/edit files, non-destructive
+            auto: ['--auto', 'high'], // full autonomy
+            skip: ['--skip-permissions-unsafe'],
+        },
+        jsonFlags: ['-o', 'stream-json'],
+        modelFlag: '-m',
+    },
 };
 /** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];
     const cmd = [...template.base];
-    const interactive = options.interactive === true || options.prompt === undefined;
-    // For Codex, 'exec' is the headless subcommand -- drop it for interactive mode
-    // so we run 'codex' (TUI) instead of 'codex exec' (one-shot)
-    if (options.agent === 'codex' && interactive && cmd[1] === 'exec') {
-        cmd.splice(1, 1);
+    const interactive = resolveInteractive(options);
+    // For Codex and Droid, 'exec' is the headless subcommand; for OpenCode, 'run'
+    // is. Drop it for interactive mode so we launch the TUI (`codex` / `droid` /
+    // `opencode`, each agent's default command) instead of the one-shot headless
+    // subcommand ('codex exec' / 'droid exec' / 'opencode run').
+    if (interactive) {
+        if ((options.agent === 'codex' || options.agent === 'droid') && cmd[1] === 'exec') {
+            cmd.splice(1, 1);
+        }
+        else if (options.agent === 'opencode' && cmd[1] === 'run') {
+            cmd.splice(1, 1);
+        }
     }
     // Use versioned alias if a specific version was requested (e.g., claude@2.1.98).
     // Resolve to the absolute path of the shim so spawn doesn't depend on PATH —
@@ -455,7 +522,12 @@ export function buildExecCommand(options) {
     // so the CLI launches its TUI. When --interactive is passed alongside a prompt
     // we still forward the prompt so the agent receives it as the first message.
     if (options.prompt !== undefined) {
-        if (template.promptFlag === 'positional') {
+        if (interactive && options.agent === 'opencode') {
+            // The OpenCode TUI takes an initial prompt via --prompt; a bare positional
+            // on the default command is parsed as a project path, not a message.
+            cmd.push('--prompt', options.prompt);
+        }
+        else if (template.promptFlag === 'positional') {
             cmd.push(options.prompt);
         }
         else {
@@ -526,7 +598,7 @@ async function spawnAgent(options) {
     const [executable, ...args] = cmd;
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
     const piped = !process.stdout.isTTY;
-    const interactive = options.interactive === true || options.prompt === undefined;
+    const interactive = resolveInteractive(options);
     maybeRotate();
     const timer = createTimer('agent.run', {
         agent: options.agent,

package/dist/lib/hooks.d.ts

@@ -123,7 +123,27 @@ export declare function listCentralHooks(): HookEntry[];
  *
  * Hooks marked `enabled: false` are dropped from the returned map.
  */
-export declare function parseHookManifest(): Record<string, ManifestHook>;
+export declare function parseHookManifest(opts?: {
+    warn?: boolean;
+}): Record<string, ManifestHook>;
+/**
+ * Hook script files present on disk that no manifest entry declares — "dead"
+ * hooks. The registrar only wires manifest-declared hooks into an agent's
+ * native config (settings.json / config.toml), matching the installed file to a
+ * manifest entry by script basename. So a file whose basename matches no
+ * manifest `script:` is never registered: it occupies the hooks dir and shows
+ * up in listings, but no lifecycle event ever fires it.
+ *
+ * Pure on purpose (no disk reads) so it is trivially testable; callers pass the
+ * installed hook names and the manifest's script paths.
+ */
+export declare function unmanagedHookNames(installedHookNames: string[], manifestScripts: string[]): string[];
+/**
+ * The dead hooks (see {@link unmanagedHookNames}) sitting in one version home.
+ * Reads the merged hook manifest silently — a diagnostic must not emit the
+ * shadow/override warnings the registrar path prints.
+ */
+export declare function listUnmanagedHooksInVersionHome(agent: AgentId, version: string): string[];
 export declare function registerHooksToSettings(agentId: AgentId, versionHome: string, hookManifest?: Record<string, ManifestHook>, agentsDirOverride?: string): {
     registered: string[];
     errors: string[];

package/dist/lib/hooks.js

@@ -8,6 +8,7 @@
  * and syncing them across version switches.
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
@@ -53,9 +54,41 @@ function getManagedHookPrefixes() {
         path.join(getSystemAgentsDir(), 'hooks') + path.sep,
     ];
 }
+/**
+ * Convert an absolute path under HOME to a portable ~/... form with forward
+ * slashes. Hook commands stored this way work on both macOS and Windows:
+ * absolute Windows paths break in bash because backslashes are stripped as
+ * escape characters, whereas ~/... paths expand correctly via the ~/.claude
+ * symlink/junction on both platforms.
+ */
+function toPortableCommand(absPath) {
+    const home = os.homedir();
+    const normalized = absPath.split(path.sep).join('/');
+    const homeNorm = home.split(path.sep).join('/');
+    if (normalized.startsWith(homeNorm + '/')) {
+        return '~/' + normalized.slice(homeNorm.length + 1);
+    }
+    return normalized;
+}
 function isManagedHookCommand(command, prefixes) {
+    // Expand ~/... so tilde-form portable commands can be matched against
+    // absolute managed prefixes.
+    let expanded = command;
+    if (command.startsWith('~/')) {
+        expanded = path.join(os.homedir(), command.slice(2));
+    }
+    // Resolve the directory through symlinks/junctions (e.g. ~/.claude on
+    // Windows is a junction to the versioned home dir where prefixes live).
+    // Resolve the dir, not the full path — the file may not exist after removal.
+    const dir = path.dirname(expanded);
+    let resolvedDir = dir;
+    try {
+        resolvedDir = fs.realpathSync(dir);
+    }
+    catch { /* absent or broken link */ }
+    const resolved = path.join(resolvedDir, path.basename(expanded));
     for (const prefix of prefixes) {
-        if (command.startsWith(prefix))
+        if (resolved.startsWith(prefix))
             return true;
     }
     return false;
@@ -80,9 +113,9 @@ function resolveHookCommand(name, hookDef, resolveScript) {
         // No caching opted in — make sure a previously generated shim from an
         // earlier `cache:` config is gone so the JSONL doesn't keep claiming hits.
         removeHookShim(name);
-        return scriptPath;
+        return toPortableCommand(scriptPath);
     }
-    return generateHookShim({ name, scriptPath, cache });
+    return toPortableCommand(generateHookShim({ name, scriptPath, cache }));
 }
 /**
  * Extensions that are NEVER hooks — docs, configuration, plain data. A file
@@ -617,7 +650,8 @@ export function listCentralHooks() {
  *
  * Hooks marked `enabled: false` are dropped from the returned map.
  */
-export function parseHookManifest() {
+export function parseHookManifest(opts = {}) {
+    const warn = opts.warn !== false;
     const merged = {};
     const systemHooks = {};
     // System layer: hooks: section of agents.yaml (npm-shipped, separate repo).
@@ -640,7 +674,7 @@ export function parseHookManifest() {
             const meta = yaml.parse(fs.readFileSync(userMetaPath, 'utf-8'));
             if (meta?.hooks)
                 for (const [name, def] of Object.entries(meta.hooks)) {
-                    if (systemHooks[name] && def.override !== true) {
+                    if (warn && systemHooks[name] && def.override !== true) {
                         const action = def.enabled === false ? 'disables' : 'shadows';
                         console.warn(`[agents hooks] User-layer hook '${name}' ${action} system-shipped hook. Set 'override: true' to silence this warning.`);
                     }
@@ -656,6 +690,35 @@ export function parseHookManifest() {
     }
     return merged;
 }
+/**
+ * Hook script files present on disk that no manifest entry declares — "dead"
+ * hooks. The registrar only wires manifest-declared hooks into an agent's
+ * native config (settings.json / config.toml), matching the installed file to a
+ * manifest entry by script basename. So a file whose basename matches no
+ * manifest `script:` is never registered: it occupies the hooks dir and shows
+ * up in listings, but no lifecycle event ever fires it.
+ *
+ * Pure on purpose (no disk reads) so it is trivially testable; callers pass the
+ * installed hook names and the manifest's script paths.
+ */
+export function unmanagedHookNames(installedHookNames, manifestScripts) {
+    const managed = new Set(manifestScripts.map((s) => path.basename(s).replace(/\.[^.]+$/, '')));
+    return installedHookNames.filter((name) => !managed.has(name)).sort();
+}
+/**
+ * The dead hooks (see {@link unmanagedHookNames}) sitting in one version home.
+ * Reads the merged hook manifest silently — a diagnostic must not emit the
+ * shadow/override warnings the registrar path prints.
+ */
+export function listUnmanagedHooksInVersionHome(agent, version) {
+    if (!AGENTS[agent].supportsHooks)
+        return [];
+    const scripts = Object.values(parseHookManifest({ warn: false }))
+        .map((h) => h.script)
+        .filter((s) => typeof s === 'string');
+    const installed = listHooksInVersionHome(agent, version).map((e) => e.name);
+    return unmanagedHookNames(installed, scripts);
+}
 // Codex events that support a matcher field (matches tool name or session type).
 // UserPromptSubmit and Stop never include a matcher.
 const CODEX_MATCHER_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'SessionStart']);
@@ -1253,8 +1316,7 @@ function registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefi
         const cmd = typeof h.command === 'string' ? h.command : '';
         if (!cmd)
             return true;
-        const isManaged = managedPrefixes.some((p) => cmd.startsWith(p));
-        if (!isManaged)
+        if (!isManagedHookCommand(cmd, managedPrefixes))
             return true;
         return currentManifestPaths.has(cmd);
     });

package/dist/lib/mcp.js

@@ -338,6 +338,35 @@ function installMcpToKimiConfig(server, versionHome) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
 }
+/**
+ * Install MCP server to Factory AI Droid config (`~/.factory/mcp.json`).
+ * Droid uses the standard `mcpServers` JSON shape, same as Kimi/Claude.
+ */
+function installMcpToFactoryConfig(server, versionHome) {
+    const configPath = path.join(versionHome, '.factory', 'mcp.json');
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+        config.mcpServers = {};
+    }
+    const mcpServers = config.mcpServers;
+    if (server.config.transport === 'stdio') {
+        mcpServers[server.name] = {
+            command: server.config.command,
+            args: server.config.args || [],
+            env: server.config.env || {},
+        };
+    }
+    else {
+        mcpServers[server.name] = {
+            url: server.config.url,
+        };
+    }
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
 function installMcpToOpenCodeConfig(server, versionHome) {
     const configPath = path.join(versionHome, '.opencode', 'opencode.jsonc');
     let config = {};
@@ -424,6 +453,10 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
                 installMcpToKimiConfig(server, versionHome);
                 applied.push(server.name);
             }
+            else if (agentId === 'droid') {
+                installMcpToFactoryConfig(server, versionHome);
+                applied.push(server.name);
+            }
         }
         catch (err) {
             const message = err.message;

package/dist/lib/models.js

@@ -772,5 +772,10 @@ export function buildReasoningFlags(agent, level) {
         const codexLevel = (normalized === 'xhigh' || normalized === 'max') ? 'high' : normalized;
         return ['-c', `model_reasoning_effort=${codexLevel}`];
     }
+    if (agent === 'droid') {
+        // Droid: `-r off|none|low|medium|high`. xhigh/max clamp to high.
+        const droidLevel = (normalized === 'xhigh' || normalized === 'max') ? 'high' : normalized;
+        return ['-r', droidLevel];
+    }
     return [];
 }

package/dist/lib/picker.d.ts

@@ -22,5 +22,7 @@ export interface PickerConfig<T> {
 export interface PickedItem<T> {
     item: T;
 }
+/** Clip a picker preview so the full prompt can fit in the terminal viewport. */
+export declare function limitPreviewHeight(preview: string, maxRows: number, width: number): string;
 /** Show an interactive fuzzy-filter picker and return the selected item, or null on cancel. */
 export declare function itemPicker<T>(config: PickerConfig<T>): Promise<PickedItem<T> | null>;

package/dist/lib/picker.js

@@ -14,6 +14,86 @@
  */
 import { createPrompt, useState, useKeypress, useEffect, useMemo, usePagination, usePrefix, makeTheme, isEnterKey, isUpKey, isDownKey, isSpaceKey, Separator, } from '@inquirer/core';
 import chalk from 'chalk';
+import { stripVTControlCharacters } from 'node:util';
+const DEFAULT_TERMINAL_ROWS = 24;
+const DEFAULT_TERMINAL_WIDTH = 80;
+function terminalWidth() {
+    return Math.max(1, process.stdout.columns || DEFAULT_TERMINAL_WIDTH);
+}
+function terminalRows() {
+    return Math.max(1, process.stdout.rows || DEFAULT_TERMINAL_ROWS);
+}
+function renderedRows(text, width) {
+    const normalizedWidth = Math.max(1, width);
+    return text.split('\n').reduce((rows, line) => {
+        const visible = stripVTControlCharacters(line).length;
+        return rows + Math.max(1, Math.ceil(visible / normalizedWidth));
+    }, 0);
+}
+function truncateAnsiLine(line, maxVisibleWidth) {
+    if (maxVisibleWidth <= 0)
+        return '';
+    const targetWidth = Math.max(0, maxVisibleWidth - 1);
+    const ansiPattern = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\))/y;
+    let out = '';
+    let visible = 0;
+    for (let i = 0; i < line.length;) {
+        ansiPattern.lastIndex = i;
+        const ansi = ansiPattern.exec(line);
+        if (ansi) {
+            out += ansi[0];
+            i = ansiPattern.lastIndex;
+            continue;
+        }
+        const char = line[i];
+        if (visible >= targetWidth)
+            break;
+        out += char;
+        visible += 1;
+        i += char.length;
+    }
+    return out + '\x1b[0m' + chalk.gray('…');
+}
+function takePreviewRows(preview, rowBudget, width) {
+    const lines = preview.split('\n');
+    const out = [];
+    let used = 0;
+    for (const line of lines) {
+        const lineRows = renderedRows(line, width);
+        if (used + lineRows <= rowBudget) {
+            out.push(line);
+            used += lineRows;
+            continue;
+        }
+        const remainingRows = rowBudget - used;
+        if (remainingRows > 0) {
+            out.push(truncateAnsiLine(line, remainingRows * width));
+        }
+        break;
+    }
+    return out;
+}
+function previewTruncatedMarker(width) {
+    const full = '... preview truncated to fit terminal';
+    const short = '... truncated';
+    const text = full.length <= width ? full : short;
+    if (text.length <= width)
+        return chalk.gray(text);
+    return chalk.gray(text.slice(0, Math.max(0, width - 1)) + '…');
+}
+/** Clip a picker preview so the full prompt can fit in the terminal viewport. */
+export function limitPreviewHeight(preview, maxRows, width) {
+    const normalizedRows = Math.max(0, maxRows);
+    if (normalizedRows === 0)
+        return '';
+    if (renderedRows(preview, width) <= normalizedRows)
+        return preview;
+    if (normalizedRows === 1)
+        return previewTruncatedMarker(width);
+    const lines = takePreviewRows(preview, normalizedRows - 1, width);
+    lines.push(previewTruncatedMarker(width));
+    return lines.join('\n');
+}
 /** Show an interactive fuzzy-filter picker and return the selected item, or null on cancel. */
 export function itemPicker(config) {
     const prompt = createPrompt((cfg, done) => {
@@ -90,18 +170,28 @@ export function itemPicker(config) {
             pageSize: cfg.pageSize ?? 10,
             loop: false,
         });
+        const enter = cfg.enterHint ?? 'select';
+        const help = previewOpen
+            ? chalk.gray(`↑↓ navigate · space: close preview · ⏎ ${enter} · esc: cancel`)
+            : chalk.gray(`↑↓ navigate${hasPreview ? ' · space: preview' : ''} · ⏎ ${enter} · esc: cancel`);
         const parts = [header, page];
         if (results.length === 0) {
             parts.push(chalk.gray(`  ${cfg.emptyMessage ?? 'No matches.'}`));
         }
         if (previewOpen && selected && cfg.buildPreview) {
-            parts.push(chalk.gray('─'.repeat(Math.min(process.stdout.columns || 80, 80))));
-            parts.push(cfg.buildPreview(selected.value));
+            const width = terminalWidth();
+            const separator = chalk.gray('─'.repeat(Math.min(width, 80)));
+            const fixedRows = renderedRows(header, width) +
+                renderedRows(parts.slice(1).join('\n'), width) +
+                renderedRows(separator, width) +
+                renderedRows(help, width);
+            const availablePreviewRows = terminalRows() - fixedRows;
+            const preview = limitPreviewHeight(cfg.buildPreview(selected.value), availablePreviewRows, width);
+            if (preview) {
+                parts.push(separator);
+                parts.push(preview);
+            }
         }
-        const enter = cfg.enterHint ?? 'select';
-        const help = previewOpen
-            ? chalk.gray(`↑↓ navigate · space: close preview · ⏎ ${enter} · esc: cancel`)
-            : chalk.gray(`↑↓ navigate${hasPreview ? ' · space: preview' : ''} · ⏎ ${enter} · esc: cancel`);
         parts.push(help);
         return [header, parts.slice(1).join('\n')];
     });

package/dist/lib/platform/index.d.ts

@@ -19,3 +19,4 @@ export * from './paths.js';
 export * from './exec.js';
 export * from './process.js';
 export * from './ipc.js';
+export * from './winpath.js';

package/dist/lib/platform/index.js

@@ -19,3 +19,4 @@ export * from './paths.js';
 export * from './exec.js';
 export * from './process.js';
 export * from './ipc.js';
+export * from './winpath.js';

package/dist/lib/platform/winpath.d.ts

@@ -0,0 +1,35 @@
+export interface WinPathResult {
+    success: boolean;
+    /** True when `dir` was already the first PATH entry (no write performed). */
+    alreadyPresent?: boolean;
+    error?: string;
+}
+/**
+ * Prepend `dir` to the Windows User PATH. Idempotent: a no-op when `dir` is
+ * already first; moves it to the front when it exists but is positioned later
+ * (e.g. appended by an older install) so it overrides conflicting entries.
+ * `dir` is passed via an env var so it is never interpolated into the script
+ * text.
+ */
+export declare function prependToWindowsUserPath(dir: string): WinPathResult;
+/**
+ * The effective PowerShell execution policy (e.g. `Restricted`, `RemoteSigned`),
+ * or null if it can't be determined (PowerShell missing / errored).
+ */
+export declare function getEffectiveExecutionPolicy(): string | null;
+/**
+ * Whether a policy blocks running unsigned local `.ps1` scripts — which is what
+ * npm and agents-cli generate (`npm.ps1`, `agents.ps1`). Under these the bare
+ * `agents` / `npm` commands fail in PowerShell with a security error even when
+ * on PATH. Pure — testable on any host.
+ */
+export declare function blocksLocalScripts(policy: string | null): boolean;
+/**
+ * Resolve the npm global-bin directory (where the generated `agents` /
+ * `agents.cmd` launchers live, and where npm expects PATH to point) from the
+ * package entrypoint. On Windows npm places bin launchers directly in the
+ * prefix root, so the bin dir is the prefix itself.
+ *
+ * entry = `<prefix>/node_modules/@phnx-labs/agents-cli/dist/index.js` → `<prefix>`
+ */
+export declare function npmGlobalBinFromEntry(entryJsPath: string): string;

package/dist/lib/platform/winpath.js

@@ -0,0 +1,86 @@
+/**
+ * Windows User PATH + execution-policy primitives.
+ *
+ * The single place that mutates the Windows User PATH via the .NET environment
+ * API (which writes the registry AND broadcasts WM_SETTINGCHANGE — the correct
+ * analog of editing a shell rc file: no `setx` truncation, no manual step).
+ * Consumers: `shims.ts` (shims dir) and `scripts/postinstall.js` (npm global-bin
+ * dir, so the `agents` command itself resolves).
+ *
+ * Leaf module — imports only `child_process` and `path` so it is cheap to load
+ * from the npm lifecycle script without pulling the rest of the CLI.
+ */
+import { execFileSync } from 'child_process';
+import * as path from 'path';
+/**
+ * Prepend `dir` to the Windows User PATH. Idempotent: a no-op when `dir` is
+ * already first; moves it to the front when it exists but is positioned later
+ * (e.g. appended by an older install) so it overrides conflicting entries.
+ * `dir` is passed via an env var so it is never interpolated into the script
+ * text.
+ */
+export function prependToWindowsUserPath(dir) {
+    const script = [
+        '$d = $env:AGENTS_WINPATH_DIR',
+        "$u = [Environment]::GetEnvironmentVariable('Path','User')",
+        "if ($null -eq $u) { $u = '' }",
+        "$parts = @($u -split ';' | Where-Object { $_ -ne '' })",
+        // Already first — nothing to do
+        "if ($parts.Count -gt 0 -and $parts[0] -eq $d) { 'present' } else {",
+        // Remove any existing occurrence then prepend, matching POSIX `export PATH="${dir}:$PATH"`
+        "  $newParts = @($d) + @($parts | Where-Object { $_ -ne $d })",
+        "  [Environment]::SetEnvironmentVariable('Path', ($newParts -join ';'), 'User')",
+        "  'added'",
+        '}',
+    ].join('\n');
+    try {
+        const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+            encoding: 'utf-8',
+            env: { ...process.env, AGENTS_WINPATH_DIR: dir },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+        return { success: true, alreadyPresent: out.includes('present') };
+    }
+    catch (err) {
+        return { success: false, error: `Could not update the Windows user PATH: ${err.message}` };
+    }
+}
+/**
+ * The effective PowerShell execution policy (e.g. `Restricted`, `RemoteSigned`),
+ * or null if it can't be determined (PowerShell missing / errored).
+ */
+export function getEffectiveExecutionPolicy() {
+    try {
+        const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', 'Get-ExecutionPolicy'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a policy blocks running unsigned local `.ps1` scripts — which is what
+ * npm and agents-cli generate (`npm.ps1`, `agents.ps1`). Under these the bare
+ * `agents` / `npm` commands fail in PowerShell with a security error even when
+ * on PATH. Pure — testable on any host.
+ */
+export function blocksLocalScripts(policy) {
+    if (!policy)
+        return false;
+    const p = policy.trim().toLowerCase();
+    return p === 'restricted' || p === 'allsigned';
+}
+/**
+ * Resolve the npm global-bin directory (where the generated `agents` /
+ * `agents.cmd` launchers live, and where npm expects PATH to point) from the
+ * package entrypoint. On Windows npm places bin launchers directly in the
+ * prefix root, so the bin dir is the prefix itself.
+ *
+ * entry = `<prefix>/node_modules/@phnx-labs/agents-cli/dist/index.js` → `<prefix>`
+ */
+export function npmGlobalBinFromEntry(entryJsPath) {
+    return path.resolve(path.dirname(entryJsPath), '..', '..', '..', '..');
+}

package/dist/lib/plugins.d.ts

@@ -41,6 +41,20 @@ export declare function discoverPlugins(opts?: {
     cwd?: string;
 }): DiscoveredPlugin[];
 export declare function buildDiscoveredPlugin(pluginRoot: string, manifest: PluginManifest, spec?: MarketplaceSpec): DiscoveredPlugin;
+/** One category of resources a plugin packages, for display breakdowns. */
+export interface PluginResourceGroup {
+    /** Category key: 'skills' | 'commands' | 'subagents' | 'hooks' | 'mcp' | 'lsp' | 'monitors' | 'bin' | 'scripts' | 'settings'. */
+    label: string;
+    /** Display names — slash-prefixed for skills/commands (e.g. `/code:dispatch`), raw names otherwise. */
+    items: string[];
+}
+/**
+ * Ordered, non-empty resource groups a plugin packages. Single source of truth
+ * for the breakdown shown by the plugin picker, `agents inspect --plugins`, and
+ * its detail view. Empty categories are omitted; `settings` appears only when
+ * the plugin merges non-permission settings.
+ */
+export declare function pluginResourceGroups(plugin: DiscoveredPlugin): PluginResourceGroup[];
 export declare function inspectPluginCapabilities(pluginRoot: string): PluginCapabilities;
 export declare function hasPluginExecSurfaces(capabilities: PluginCapabilities): boolean;
 export declare function pluginCapabilityLabels(capabilities: PluginCapabilities): string[];
@@ -60,6 +74,16 @@ export declare function getPlugin(name: string): DiscoveredPlugin | null;
  * Otherwise defaults to all plugin-capable agents.
  */
 export declare function pluginSupportsAgent(plugin: DiscoveredPlugin, agent: AgentId): boolean;
+/**
+ * The lifecycle events a plugin hooks into, read from hooks/hooks.json.
+ *
+ * The official plugin format wraps the event map under a `hooks` key
+ * (`{ description, hooks: { SessionStart: [...], PreToolUse: [...] } }`), so the
+ * meaningful keys are the events — NOT the top-level keys (`description`,
+ * `hooks`). Older/flat files put the event names at the top level directly; we
+ * read whichever object actually holds the event map.
+ */
+export declare function discoverPluginHooks(pluginRoot: string): string[];
 /** Discover command .md files inside a plugin's commands/ directory. */
 export declare function discoverPluginCommands(pluginRoot: string): string[];
 /** Discover agent definition .md files inside a plugin's agents/ directory. */