@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/commands/skills.js

@@ -7,9 +7,9 @@ import { select, checkbox } from '@inquirer/prompts';
 import { AGENTS, SKILLS_CAPABLE_AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverSkillsFromRepo, installSkillCentrally, listInstalledSkills, listInstalledSkillsWithScope, getSkillInfo, getSkillRules, getSkillsDir, countSkillFiles, tryParseSkillMetadata, diffVersionSkills, iterSkillsCapableVersions, removeSkillFromVersion, } from '../lib/skills.js';
-import { getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, promptRemovalTargets, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Register the `agents skills` command tree (list, add, remove, sync, prune, view). */
 export function registerSkillsCommands(program) {
@@ -202,11 +202,24 @@ Examples:
                         spinner.succeed('Using local path');
                     }
                 }
-                console.log(chalk.bold(`\nFound ${discoveredSkills.length} skill(s):`));
                 if (discoveredSkills.length === 0) {
                     console.log(chalk.yellow('No skills found (looking for SKILL.md files)'));
                     return;
                 }
+                // Filter by --names if provided. Mirrors the no-source path's behavior
+                // so users can pluck specific skills from a multi-skill repo.
+                const requestedNames = parseCommaSeparatedList(options.names);
+                if (requestedNames.length > 0) {
+                    const discoveredNames = new Set(discoveredSkills.map((s) => s.name));
+                    const missing = requestedNames.filter((n) => !discoveredNames.has(n));
+                    if (missing.length > 0) {
+                        console.log(chalk.red(`\nSkill(s) not found in source: ${missing.join(', ')}`));
+                        console.log(chalk.gray(`Available: ${[...discoveredNames].join(', ')}`));
+                        process.exit(1);
+                    }
+                    discoveredSkills = discoveredSkills.filter((s) => requestedNames.includes(s.name));
+                }
+                console.log(chalk.bold(`\nFound ${discoveredSkills.length} skill(s):`));
                 for (const skill of discoveredSkills) {
                     const nameColor = skill.parseError ? chalk.yellow : chalk.cyan;
                     console.log(`\n  ${nameColor(skill.name)}: ${skill.metadata.description || 'no description'}`);
@@ -238,13 +251,17 @@ Examples:
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
-                const result = resolveAgentVersionTargets(options.agents, SKILLS_CAPABLE_AGENTS);
+                const result = await resolveAgentTargetsAutoInstalling(options.agents, SKILLS_CAPABLE_AGENTS, { yes: options.yes });
+                if (!result) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
             }
             else {
                 const result = await promptAgentVersionSelection(SKILLS_CAPABLE_AGENTS, {
-                    skipPrompts: options.yes || !isInteractiveTerminal(),
+                    skipPrompts: options.yes,
                 });
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
@@ -394,17 +411,17 @@ Examples:
         .action(() => {
         console.error(chalk.red('"agents skills sync" is gone.'));
         console.error(chalk.gray('Sync runs automatically when you launch the agent.'));
-        console.error(chalk.gray('To remove orphans, use:  agents prune skills'));
+        console.error(chalk.gray('To remove orphans, use:  agents prune cleanup skills'));
         process.exit(1);
     });
-    // `skills prune` moved to the top-level `agents prune` command.
+    // `skills prune` moved to the top-level `agents prune cleanup` command.
     skillsCmd
         .command('prune', { hidden: true })
         .allowUnknownOption()
         .allowExcessArguments()
         .action(() => {
         console.error(chalk.red('"agents skills prune" moved.'));
-        console.error(chalk.gray('Use:  agents prune skills   (or `agents prune` for everything)'));
+        console.error(chalk.gray('Use:  agents prune cleanup skills   (or `agents prune cleanup` for everything)'));
         process.exit(1);
     });
     skillsCmd

package/dist/commands/subagents.js

@@ -9,13 +9,12 @@ import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
-import { checkbox } from '@inquirer/prompts';
-import { AGENTS, agentLabel } from '../lib/agents.js';
+import { agentLabel } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverSubagentsFromRepo, installSubagentCentrally, listInstalledSubagents, getInstalledSubagent, listSubagentsForAgent, SUBAGENT_CAPABLE_AGENTS, iterSubagentsCapableVersions, removeSubagentFromVersion, } from '../lib/subagents.js';
-import { listInstalledVersions, syncResourcesToVersion, getGlobalDefault, getVersionHomePath, } from '../lib/versions.js';
-import { getSubagentsDir } from '../lib/state.js';
-import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection, requireDestructiveArg, promptRemovalTargets, } from './utils.js';
+import { listInstalledVersions, syncResourcesToVersion, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, } from '../lib/versions.js';
+import { getSubagentsDir, recordVersionResources } from '../lib/state.js';
+import { requireDestructiveArg, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Replace the home directory prefix with ~ for display. */
 function formatPath(p) {
@@ -102,13 +101,20 @@ Examples:
     subagentsCmd
         .command('add <source>')
         .description('Install subagents from a source (GitHub, local path) and sync to agent versions')
-        .option('-a, --agents <agents...>', 'Targets: claude, openclaw (defaults to all subagent-capable agents)')
+        .option('-a, --agents <list>', 'Targets: claude, openclaw, claude@2.1.141, claude@all, all')
+        .option('--names <list>', 'Subagent names from the source (comma-separated)')
         .option('-y, --yes', 'Skip all prompts and confirmations')
         .addHelpText('after', `
 Examples:
   # Install from GitHub
   agents subagents add gh:team/subagents --agents claude,openclaw
 
+  # Pluck specific subagents from a multi-subagent repo
+  agents subagents add gh:team/subagents --names code-reviewer,planner
+
+  # Install across every installed Claude version
+  agents subagents add gh:team/subagents --agents claude@all
+
   # Install from local directory (must contain subagents/*/AGENT.md)
   agents subagents add ~/my-subagent --agents claude
 
@@ -117,9 +123,13 @@ Examples:
 `)
         .action(async (source, options) => {
         const spinner = ora({ text: 'Fetching source...', isSilent: !process.stdout.isTTY }).start();
-        // Clone or use local source
+        // Clone or use local source. Accept any git-like scheme to match the
+        // other <resource> add commands (skills, workflows, commands, hooks).
         let sourcePath;
-        if (source.startsWith('gh:') || source.startsWith('http')) {
+        const isGitRepo = source.startsWith('gh:') || source.startsWith('git:') ||
+            source.startsWith('ssh:') || source.startsWith('https://') ||
+            source.startsWith('http://');
+        if (isGitRepo) {
             try {
                 const cloneResult = await cloneRepo(source);
                 sourcePath = cloneResult.localPath;
@@ -138,12 +148,24 @@ Examples:
         }
         // Discover subagents
         spinner.text = 'Discovering subagents...';
-        const discovered = discoverSubagentsFromRepo(sourcePath);
+        let discovered = discoverSubagentsFromRepo(sourcePath);
         if (discovered.length === 0) {
             spinner.fail('No subagents found in source');
             console.log(chalk.gray(`Expected: subagents/*/AGENT.md`));
             process.exit(1);
         }
+        // --names filter: pluck specific subagents from a multi-subagent source.
+        const requestedNames = parseCommaSeparatedList(options.names);
+        if (requestedNames.length > 0) {
+            const discoveredNames = new Set(discovered.map((s) => s.name));
+            const missing = requestedNames.filter((n) => !discoveredNames.has(n));
+            if (missing.length > 0) {
+                spinner.fail(`Subagent(s) not found in source: ${missing.join(', ')}`);
+                console.log(chalk.gray(`Available: ${[...discoveredNames].join(', ')}`));
+                process.exit(1);
+            }
+            discovered = discovered.filter((s) => requestedNames.includes(s.name));
+        }
         spinner.succeed(`Found ${discovered.length} subagent(s)`);
         // Show what we found
         console.log();
@@ -151,42 +173,29 @@ Examples:
             console.log(`  ${chalk.cyan(sub.name)}: ${chalk.gray(sub.frontmatter.description)}`);
         }
         console.log();
-        // Determine target agents
-        let targetAgents = options.agents || [];
-        if (targetAgents.length === 0 && !options.yes) {
-            // Prompt for target agents
-            const installedAgents = SUBAGENT_CAPABLE_AGENTS.filter(id => {
-                const versions = listInstalledVersions(id);
-                return versions.length > 0;
-            });
-            if (installedAgents.length === 0) {
-                console.log(chalk.yellow('No subagent-capable agents installed'));
-                console.log(chalk.gray('Subagents will be stored centrally and synced when you install claude or openclaw'));
-                targetAgents = [];
-            }
-            else {
-                if (!isInteractiveTerminal()) {
-                    requireInteractiveSelection('Selecting target agents for subagents', [
-                        'agents subagents add <source> --agents claude openclaw',
-                        'agents subagents add <source> --yes',
-                    ]);
-                }
-                try {
-                    targetAgents = await checkbox({
-                        message: 'Install to which agents?',
-                        choices: installedAgents.map(id => ({
-                            name: AGENTS[id].name,
-                            value: id,
-                            checked: true,
-                        })),
-                    });
-                }
-                catch (err) {
-                    if (isPromptCancelled(err))
-                        return;
-                    throw err;
-                }
+        // Determine target agent versions, using the same path skills/workflows use.
+        // Back-compat: commander's old `--agents <agents...>` shape arrives as an array;
+        // join it with commas so resolveAgentVersionTargets can parse it.
+        const agentsArg = Array.isArray(options.agents)
+            ? options.agents.join(',')
+            : options.agents;
+        let selectedAgents;
+        let versionSelections;
+        if (agentsArg) {
+            const result = await resolveAgentTargetsAutoInstalling(agentsArg, SUBAGENT_CAPABLE_AGENTS, { yes: options.yes });
+            if (!result) {
+                console.log(chalk.gray('Cancelled.'));
+                return;
             }
+            selectedAgents = result.selectedAgents;
+            versionSelections = result.versionSelections;
+        }
+        else {
+            const result = await promptAgentVersionSelection(SUBAGENT_CAPABLE_AGENTS, {
+                skipPrompts: options.yes,
+            });
+            selectedAgents = result.selectedAgents;
+            versionSelections = result.versionSelections;
         }
         // Install centrally
         const installSpinner = ora({ text: 'Installing subagents...', isSilent: !process.stdout.isTTY }).start();
@@ -198,16 +207,27 @@ Examples:
             }
         }
         installSpinner.succeed(`Installed ${discovered.length} subagent(s) to ${formatPath(getSubagentsDir())}`);
-        // Sync to target agents
-        if (targetAgents.length > 0) {
+        // Sync to selected versions
+        if (versionSelections.size > 0) {
             const syncSpinner = ora({ text: 'Syncing to agents...', isSilent: !process.stdout.isTTY }).start();
-            for (const agentId of targetAgents) {
-                const versions = listInstalledVersions(agentId);
+            const subagentNames = discovered.map((s) => s.name);
+            let synced = 0;
+            for (const [agentId, versions] of versionSelections) {
                 for (const version of versions) {
                     syncResourcesToVersion(agentId, version);
+                    recordVersionResources(agentId, version, 'subagents', subagentNames);
+                    synced++;
                 }
             }
-            syncSpinner.succeed(`Synced to ${targetAgents.map(id => agentLabel(id)).join(', ')}`);
+            if (synced > 0) {
+                syncSpinner.succeed(`Synced to ${synced} agent version(s) across ${selectedAgents.map((id) => agentLabel(id)).join(', ')}`);
+            }
+            else {
+                syncSpinner.info('No version-managed agents to sync');
+            }
+        }
+        else {
+            console.log(chalk.gray('Stored centrally; no agent versions selected for sync.'));
         }
         console.log();
     });

package/dist/commands/teams.js

@@ -14,6 +14,7 @@ import { buildPreview as buildSessionPreview } from './sessions-picker.js';
 import { parseExecEnv } from '../lib/exec.js';
 import { teamPicker, printTeamTable } from './teams-picker.js';
 import { itemPicker } from '../lib/picker.js';
+import { profileExists, readProfile } from '../lib/profiles.js';
 import { isPromptCancelled, isInteractiveTerminal, requireDestructiveArg, requireInteractiveSelection, } from './utils.js';
 const AGENT_NAMES = {
     claude: 'Claude',
@@ -21,9 +22,12 @@ const AGENT_NAMES = {
     gemini: 'Gemini',
     cursor: 'Cursor',
     opencode: 'OpenCode',
+    grok: 'Grok',
+    antigravity: 'Antigravity',
 };
 const VALID_AGENTS = Object.keys(AGENT_NAMES);
-const VALID_MODES = ['plan', 'edit', 'full'];
+// 'full' kept as historical alias for 'skip'; normalized to 'skip' downstream.
+const VALID_MODES = ['plan', 'edit', 'auto', 'skip', 'full'];
 const VALID_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'auto'];
 const VALID_CLOUD_PROVIDERS = ['rush', 'codex', 'factory'];
 // Auto-enable JSON mode when piped / not a TTY so AI agent consumers get
@@ -85,14 +89,48 @@ function fullName(type, version) {
     const name = AGENT_NAMES[type];
     return version ? `${name} ${version}` : name;
 }
+/**
+ * Resolve a teammate spec to its execution target.
+ *
+ * Accepts:
+ *  - `claude`            — default version of an installed agent
+ *  - `claude@2.1.112`    — pinned version of an installed agent
+ *  - `<profile-name>`    — runs through `agents run <profile>`, with the
+ *                          profile's host agent used as the underlying
+ *                          AgentType for event parsing and CLI checks.
+ *
+ * `agent` is always the underlying harness so event parsers, CLI-availability
+ * checks, and version pins keep working. `profileName` is set only when the
+ * spec resolved through a profile.
+ */
 function parseTeammate(spec) {
     const [name, version] = spec.split('@');
-    if (!VALID_AGENTS.includes(name)) {
-        die(`Unknown teammate '${name}'. Available: ${VALID_AGENTS.join(', ')}.\n` +
-            `  Use the form 'claude' or 'claude@2.1.112' (see 'agents view' for installed versions).`);
+    if (VALID_AGENTS.includes(name)) {
+        const agent = name;
+        return {
+            agent,
+            version: resolveVersionAlias(agent, version) ?? null,
+            profileName: null,
+        };
+    }
+    // Not a built-in agent id — try resolving as a profile name. A profile
+    // pinning a version is allowed; `profile@<override>` is not (would conflict
+    // with the profile's own host.version).
+    if (!version && profileExists(name)) {
+        try {
+            const profile = readProfile(name);
+            return {
+                agent: profile.host.agent,
+                version: profile.host.version ?? null,
+                profileName: profile.name,
+            };
+        }
+        catch (err) {
+            die(`Profile '${name}' is malformed: ${err.message}`);
+        }
     }
-    const agent = name;
-    return { agent, version: resolveVersionAlias(agent, version) ?? null };
+    die(`Unknown teammate '${spec}'. Available agents: ${VALID_AGENTS.join(', ')}.\n` +
+        `  Use 'claude', 'claude@2.1.112', or the name of a profile from 'agents view'.`);
 }
 function shortId(id) {
     return id.slice(0, 8);
@@ -545,6 +583,8 @@ export function registerTeamsCommands(program) {
       Teammate syntax:
         'claude'           the default Claude version on this machine
         'claude@2.1.112'   a specific installed version (see 'agents view')
+        '<profile>'        a profile from 'agents view' — runs through 'agents
+                           run <profile>' with the profile's host harness
 
       Short aliases:
         teams c  = create    teams a  = add       teams s  = status
@@ -709,7 +749,7 @@ export function registerTeamsCommands(program) {
         .alias('a')
         .description("Add a teammate to work on a task. Runs in background; returns immediately. Use 'status' to check in.")
         .option('-n, --name <name>', 'Friendly name for this teammate (e.g. alice). Required if using --after. Unique within team.')
-        .option('-m, --mode <mode>', `Permissions: plan (read-only) | edit (can write files) | full (write + skip permission prompts)`, 'edit')
+        .option('-m, --mode <mode>', `Permissions: plan (read-only) | edit (can write files) | auto (smart classifier auto-approves safe ops) | skip (bypass all permission prompts). 'full' accepted as alias for skip.`, 'edit')
         .option('-e, --effort <effort>', `Reasoning intensity: ${VALID_EFFORTS.join('|')}`, 'medium')
         .option('--model <model>', 'Override the effort tier and use this specific model (e.g. claude-opus-4-6)')
         .option('--env <key=value>', 'Set an environment variable for this teammate (repeatable for multiple vars)', (val, prev) => [...prev, val], [])
@@ -745,7 +785,7 @@ export function registerTeamsCommands(program) {
                 die(`--cloud rush requires --repo <owner/repo>`);
             }
         }
-        const { agent, version } = parseTeammate(teammate);
+        const { agent, version, profileName } = parseTeammate(teammate);
         if (version && !isVersionInstalled(agent, version)) {
             die(`${AGENT_NAMES[agent]} ${version} isn't installed.\n` +
                 `  Install it:  agents add ${agent}@${version}\n` +
@@ -756,6 +796,11 @@ export function registerTeamsCommands(program) {
                 die(`Invalid teammate name '${opts.name}'. Use letters, numbers, '-', or '_'.`);
             }
         }
+        if (opts.worktree !== undefined) {
+            if (!opts.worktree || !/^[A-Za-z0-9_-]+$/.test(opts.worktree)) {
+                die(`Invalid worktree name '${opts.worktree}'. Use letters, numbers, '-', or '_'.`);
+            }
+        }
         const after = opts.after
             ? opts.after.split(',').map((s) => s.trim()).filter(Boolean)
             : [];
@@ -865,12 +910,12 @@ export function registerTeamsCommands(program) {
             }
         }
         try {
-            const result = await handleSpawn(mgr, team, agent, effectiveTask, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null, taskType, cloudProviderId, cloudSessionId, opts.repo ?? null, opts.branch ?? null, worktreeName, worktreePath);
+            const result = await handleSpawn(mgr, team, agent, effectiveTask, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null, taskType, cloudProviderId, cloudSessionId, opts.repo ?? null, opts.branch ?? null, worktreeName, worktreePath, profileName);
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify(result, null, 2));
                 return;
             }
-            const who = fullName(agent, version);
+            const who = profileName ? `${profileName} (via ${fullName(agent, version)})` : fullName(agent, version);
             const staged = result.status === 'pending';
             const verb = staged ? 'Staged' : 'Welcomed';
             const greeting = result.name
@@ -899,6 +944,12 @@ export function registerTeamsCommands(program) {
             console.log();
             if (staged) {
                 console.log(chalk.gray(`Start the ready teammates:  agents teams start ${team}`));
+                if (after.length > 0) {
+                    process.stderr.write(chalk.yellow(`\nWarning: this teammate has --after dependencies and will NEVER start on its own.\n` +
+                        `  A supervisor watch process is required to launch it when its deps complete.\n` +
+                        `  Run this in another terminal:\n` +
+                        `    agents teams start ${team} --watch\n`));
+                }
             }
             else {
                 console.log(chalk.gray(`Check in later:  agents teams status ${team}`));

package/dist/commands/utils.d.ts

@@ -4,6 +4,8 @@
  * Small helpers used across multiple commands: prompt cancellation detection,
  * table formatting, spinner management, and platform-specific workarounds.
  */
+import type { AgentId } from '../lib/types.js';
+import { type InstalledAgentTargetResult, type VersionSelectionResult } from '../lib/versions.js';
 /**
  * Check if an error is from user cancelling a prompt (Ctrl+C)
  */
@@ -58,3 +60,34 @@ export declare function promptRemovalTargets(resourceName: string, targets: Remo
  * Format a path for display, using ~ for home directory
  */
 export declare function formatPath(fullPath: string, cwd?: string): string;
+/**
+ * Make sure every specific `agent@x.y.z` the user typed is installed before
+ * the caller resolves targets. Returns true if the caller should continue,
+ * false if the user declined the prompt. Exported so non-standard caller
+ * shapes (e.g. mcp.ts's manifest-shaped parser) can run the pre-flight
+ * without going through resolveAgentVersionTargets first.
+ */
+export declare function ensureAgentVersionsInstalled(value: string, availableAgents: readonly AgentId[], options?: {
+    yes?: boolean;
+}): Promise<boolean>;
+/**
+ * Resolve a `--agents` selector and, if any requested `agent@version` isn't
+ * installed yet, prompt to install it (or auto-install with --yes) before
+ * delegating to resolveAgentVersionTargets. Returns null when the user
+ * declines the install prompt — callers should treat that as a clean cancel.
+ */
+export declare function resolveAgentTargetsAutoInstalling(value: string, availableAgents: readonly AgentId[], options?: {
+    yes?: boolean;
+    allVersions?: boolean;
+}): Promise<VersionSelectionResult | null>;
+/**
+ * Same as resolveAgentTargetsAutoInstalling but returns the broader
+ * InstalledAgentTargetResult that includes `directAgents` (for paths like
+ * `agents install` and `mcp register` that fall through to unmanaged homes
+ * when no managed version is installed).
+ */
+export declare function resolveInstalledAgentTargetsAutoInstalling(value: string, availableAgents: readonly AgentId[], options?: {
+    yes?: boolean;
+    allVersions?: boolean;
+}): Promise<InstalledAgentTargetResult | null>;
+export { VersionNotInstalledError } from '../lib/versions.js';

package/dist/commands/utils.js

@@ -7,6 +7,10 @@
 import * as os from 'os';
 import { spawnSync } from 'child_process';
 import chalk from 'chalk';
+import ora from 'ora';
+import { confirm } from '@inquirer/prompts';
+import { agentLabel, resolveAgentName } from '../lib/agents.js';
+import { installVersion, listInstalledVersions, resolveAgentVersionTargets, resolveInstalledAgentTargets, } from '../lib/versions.js';
 /**
  * Check if an error is from user cancelling a prompt (Ctrl+C)
  */
@@ -135,3 +139,138 @@ export function formatPath(fullPath, cwd) {
     }
     return fullPath;
 }
+/**
+ * Parse a --agents selector and collect every (agentId, specificVersion) pair
+ * the user requested where the version is a concrete x.y.z (not `default`,
+ * not `all`, not `latest`) and is NOT currently installed.
+ *
+ * This is the lookahead the auto-install wrappers use to decide whether to
+ * prompt + install before delegating to resolveAgentVersionTargets.
+ */
+function collectMissingVersions(value, availableAgents) {
+    const missing = [];
+    const seen = new Set();
+    for (const raw of value.split(',').map((s) => s.trim()).filter(Boolean)) {
+        // Literal `all` / `all@all` expand to per-agent — never missing.
+        if (raw === 'all' || raw === 'all@all')
+            continue;
+        const atIndex = raw.indexOf('@');
+        if (atIndex === -1)
+            continue; // bare agent → resolves to default; never missing in this sense
+        const agentToken = raw.slice(0, atIndex).trim();
+        const versionToken = raw.slice(atIndex + 1).trim();
+        // Non-specific selectors handled by the underlying resolver.
+        if (!versionToken || versionToken === 'default' || versionToken === 'all')
+            continue;
+        const agentId = resolveAgentName(agentToken);
+        if (!agentId || !availableAgents.includes(agentId))
+            continue;
+        const installed = listInstalledVersions(agentId);
+        if (installed.includes(versionToken))
+            continue;
+        const key = `${agentId}@${versionToken}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        missing.push({ agentId, version: versionToken });
+    }
+    return missing;
+}
+/**
+ * Sequentially install every requested missing version with a per-version
+ * spinner. Aborts via process.exit(1) on the first failure — the user
+ * already approved the install so a partial-install outcome is worse than
+ * a hard stop.
+ */
+async function installMissingVersions(missing) {
+    for (const { agentId, version } of missing) {
+        const label = `${agentLabel(agentId)}@${version}`;
+        const spinner = ora(`Installing ${label}...`).start();
+        try {
+            const result = await installVersion(agentId, version, (msg) => {
+                spinner.text = msg;
+            });
+            if (!result.success) {
+                spinner.fail(`Failed to install ${label}: ${result.error ?? 'unknown error'}`);
+                process.exit(1);
+            }
+            spinner.succeed(`Installed ${label}`);
+        }
+        catch (err) {
+            spinner.fail(`Failed to install ${label}: ${err.message}`);
+            process.exit(1);
+        }
+    }
+}
+/**
+ * Make sure every specific `agent@x.y.z` the user typed is installed before
+ * the caller resolves targets. Returns true if the caller should continue,
+ * false if the user declined the prompt. Exported so non-standard caller
+ * shapes (e.g. mcp.ts's manifest-shaped parser) can run the pre-flight
+ * without going through resolveAgentVersionTargets first.
+ */
+export async function ensureAgentVersionsInstalled(value, availableAgents, options = {}) {
+    const missing = collectMissingVersions(value, availableAgents);
+    if (missing.length === 0)
+        return true;
+    const summary = missing.map((m) => `${agentLabel(m.agentId)}@${m.version}`).join(', ');
+    if (!options.yes) {
+        if (!isInteractiveTerminal()) {
+            console.error(chalk.red(`Missing agent version(s): ${summary}`));
+            console.error(chalk.gray('In a scripted shell, opt in to auto-install:'));
+            console.error(chalk.cyan(`  rerun with --yes`));
+            console.error(chalk.gray('Or pre-install:'));
+            for (const m of missing) {
+                console.error(chalk.cyan(`  agents add ${m.agentId}@${m.version}`));
+            }
+            process.exit(1);
+        }
+        console.log(chalk.yellow(`\nThe following agent version(s) are not installed:`));
+        for (const m of missing) {
+            console.log(`  ${chalk.cyan(`${agentLabel(m.agentId)}@${m.version}`)}`);
+        }
+        let proceed;
+        try {
+            proceed = await confirm({
+                message: `Install ${missing.length} missing version${missing.length === 1 ? '' : 's'}?`,
+                default: true,
+            });
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return false;
+            throw err;
+        }
+        if (!proceed)
+            return false;
+    }
+    await installMissingVersions(missing);
+    return true;
+}
+/**
+ * Resolve a `--agents` selector and, if any requested `agent@version` isn't
+ * installed yet, prompt to install it (or auto-install with --yes) before
+ * delegating to resolveAgentVersionTargets. Returns null when the user
+ * declines the install prompt — callers should treat that as a clean cancel.
+ */
+export async function resolveAgentTargetsAutoInstalling(value, availableAgents, options = {}) {
+    const ok = await ensureAgentVersionsInstalled(value, availableAgents, options);
+    if (!ok)
+        return null;
+    return resolveAgentVersionTargets(value, availableAgents, { allVersions: options.allVersions });
+}
+/**
+ * Same as resolveAgentTargetsAutoInstalling but returns the broader
+ * InstalledAgentTargetResult that includes `directAgents` (for paths like
+ * `agents install` and `mcp register` that fall through to unmanaged homes
+ * when no managed version is installed).
+ */
+export async function resolveInstalledAgentTargetsAutoInstalling(value, availableAgents, options = {}) {
+    const ok = await ensureAgentVersionsInstalled(value, availableAgents, options);
+    if (!ok)
+        return null;
+    return resolveInstalledAgentTargets(value, availableAgents, { allVersions: options.allVersions });
+}
+// Re-export so callers can `catch (err) { if (err instanceof VersionNotInstalledError) … }`
+// without reaching into ../lib/versions directly.
+export { VersionNotInstalledError } from '../lib/versions.js';

package/dist/commands/versions.d.ts

@@ -1,10 +1,11 @@
 /**
  * Version management commands for installing, switching, and removing agent CLIs.
  *
- * Implements `agents add`, `agents remove`, `agents use`, and the deprecated
- * `agents list`. Handles npm-based installation, shim creation, config symlink
+ * Implements `agents add`, `agents prune`, `agents remove` (alias),
+ * `agents use`, and the deprecated `agents list`. Handles npm-based installation,
+ * shim creation, config symlink
  * switching, resource sync prompts, and project-level version pinning.
  */
 import type { Command } from 'commander';
-/** Register `agents add`, `agents remove`, `agents use`, and `agents list` (deprecated). */
+/** Register `agents add`, `agents prune`, `agents remove`, `agents use`, and `agents list` (deprecated). */
 export declare function registerVersionsCommands(program: Command): void;