@phnx-labs/agents-cli 1.20.12 → 1.20.14

package/dist/commands/plugins.js

@@ -12,7 +12,7 @@ import { homeDir } from '../lib/platform/index.js';
 import { input } from '@inquirer/prompts';
 import { agentLabel } from '../lib/agents.js';
 import { capableAgents, isCapable } from '../lib/capabilities.js';
-import { discoverPlugins, getPlugin, pluginSupportsAgent, removePluginFromVersion, isPluginSynced, installPlugin, updatePlugin, loadUserConfig, saveUserConfig, checkPluginDependencies, hasPluginExecSurfaces, inspectPluginCapabilities, pluginCapabilityLabels, parseInstallSpec, syncPluginToVersion, } from '../lib/plugins.js';
+import { discoverPlugins, getPlugin, pluginSupportsAgent, removePluginFromVersion, isPluginSynced, installPlugin, updatePlugin, loadUserConfig, saveUserConfig, checkPluginDependencies, hasPluginExecSurfaces, inspectPluginCapabilities, pluginCapabilityLabels, parseInstallSpec, syncPluginToVersion, pluginResourceGroups, } from '../lib/plugins.js';
 import { listInstalledVersions, syncResourcesToVersion, getGlobalDefault, getVersionHomePath, } from '../lib/versions.js';
 import { isPromptCancelled, isInteractiveTerminal, requireDestructiveArg, requireInteractiveSelection, promptRemovalTargets, } from './utils.js';
 import { itemPicker } from '../lib/picker.js';
@@ -276,14 +276,17 @@ Examples:
     // agents plugins sync <name> [agent]
     pluginsCmd
         .command('sync <name> [agent]')
-        .description('Apply a plugin to the default version of an agent (or all supported agents if none specified)')
+        .description('Apply a plugin to an agent. Syncs every installed version (pass agent@version to target one).')
         .option('--allow-exec-surfaces', 'Enable the plugin even when it ships hooks/, .mcp.json, bin/, scripts/, settings.json, or permissions/')
         .addHelpText('after', `
 Examples:
-  # Sync a plugin to a specific agent (default version)
+  # Sync a plugin to every installed version of an agent
   agents plugins sync rush-toolkit claude
 
-  # Sync to all supported agents
+  # Sync to one specific version (parity with 'agents sync')
+  agents plugins sync rush-toolkit claude@2.1.142
+
+  # Sync to all supported agents (every installed version of each)
   agents plugins sync rush-toolkit
 
   # Re-affirm consent for a hooks-bearing plugin
@@ -295,12 +298,22 @@ Examples:
             console.log(chalk.red(`Plugin '${name}' not found`));
             process.exit(1);
         }
+        // Accept the same "agent@version" form as `agents sync`. Splitting here
+        // also means an unknown spec is reported cleanly rather than crashing
+        // isCapable() with a bare "claude@2.1.168".
+        let versionArg;
+        let agentName = agentArg;
+        if (agentArg && agentArg.includes('@')) {
+            const at = agentArg.lastIndexOf('@');
+            agentName = agentArg.slice(0, at);
+            versionArg = agentArg.slice(at + 1);
+        }
         // Determine target agents
         let targetAgents;
-        if (agentArg) {
-            const agentId = agentArg;
+        if (agentName) {
+            const agentId = agentName;
             if (!isCapable(agentId, 'plugins')) {
-                console.log(chalk.red(`Agent '${agentArg}' does not support plugins`));
+                console.log(chalk.red(`Agent '${agentName}' does not support plugins`));
                 process.exit(1);
             }
             if (!pluginSupportsAgent(plugin, agentId)) {
@@ -310,6 +323,10 @@ Examples:
             targetAgents = [agentId];
         }
         else {
+            if (versionArg) {
+                console.log(chalk.red(`A version (@${versionArg}) requires naming the agent, e.g. claude@${versionArg}`));
+                process.exit(1);
+            }
             targetAgents = capableAgents('plugins').filter(a => pluginSupportsAgent(plugin, a));
         }
         const allowExec = options.allowExecSurfaces === true;
@@ -317,8 +334,21 @@ Examples:
             const versions = listInstalledVersions(agentId);
             if (versions.length === 0)
                 continue;
-            const defaultVer = getGlobalDefault(agentId);
-            const targetVersions = defaultVer ? [defaultVer] : [versions[versions.length - 1]];
+            // Default to EVERY installed version. The previous behaviour synced only
+            // the global default, which silently skipped non-default versions used
+            // by balanced rotation -- so a rotated version would lack the plugin's
+            // slash commands. An explicit agent@version narrows back to one.
+            let targetVersions;
+            if (versionArg) {
+                if (!versions.includes(versionArg)) {
+                    console.log(chalk.red(`${agentLabel(agentId)} has no installed version ${versionArg} (installed: ${versions.join(', ')})`));
+                    process.exit(1);
+                }
+                targetVersions = [versionArg];
+            }
+            else {
+                targetVersions = versions;
+            }
             for (const version of targetVersions) {
                 const didSync = allowExec
                     ? syncPluginToVersion(plugin, agentId, getVersionHomePath(agentId, version), { allowExecSurfaces: true, version }).success
@@ -711,6 +741,32 @@ function buildPluginRows(plugins) {
     });
     return rows;
 }
+/** Per-category color for a plugin resource breakdown (shared with `agents inspect`). */
+export const PLUGIN_GROUP_COLORS = {
+    skills: chalk.cyan,
+    commands: chalk.cyan,
+    subagents: chalk.magenta,
+    hooks: chalk.yellow,
+    mcp: chalk.green,
+    lsp: chalk.green,
+    monitors: chalk.blue,
+    bin: chalk.white,
+    scripts: chalk.white,
+    settings: chalk.gray,
+};
+/** Human-readable section header per category, used by the picker detail pane. */
+const PLUGIN_GROUP_TITLES = {
+    skills: 'Skills',
+    commands: 'Commands',
+    subagents: 'Subagents',
+    hooks: 'Hooks',
+    mcp: 'MCP Servers',
+    lsp: 'LSP Servers',
+    monitors: 'Monitors',
+    bin: 'Bin',
+    scripts: 'Scripts',
+    settings: 'Settings',
+};
 /** Build the multi-line detail pane shown when a plugin is selected in the picker. */
 function formatPluginDetail(plugin, targets) {
     const lines = [];
@@ -728,24 +784,11 @@ function formatPluginDetail(plugin, targets) {
         lines.push('  ' + chalk.gray('Supports: ') + supported.join(chalk.gray(' · ')));
     }
     lines.push('  ' + chalk.gray(formatPath(plugin.root)));
-    const section = (label, items, colorFn) => {
-        if (items.length === 0)
-            return;
+    for (const group of pluginResourceGroups(plugin)) {
+        const colorFn = PLUGIN_GROUP_COLORS[group.label] ?? chalk.white;
         lines.push('');
-        lines.push(chalk.bold(`  ${label}`));
-        lines.push('  ' + items.map(colorFn).join(chalk.gray(', ')));
-    };
-    section('Skills', plugin.skills.map((s) => `/${plugin.name}:${s}`), chalk.cyan);
-    section('Commands', plugin.commands.map((c) => `/${plugin.name}:${c}`), chalk.cyan);
-    section('Subagents', plugin.agentDefs, chalk.magenta);
-    section('Hooks', plugin.hooks, chalk.yellow);
-    section('MCP Servers', plugin.mcpServers, chalk.green);
-    section('LSP Servers', plugin.lspServers, chalk.green);
-    section('Monitors', plugin.monitors, chalk.blue);
-    section('Bin', plugin.bin, chalk.white);
-    section('Scripts', plugin.scripts, chalk.white);
-    if (plugin.hasSettings) {
-        section('Settings', ['settings.json'], chalk.gray);
+        lines.push(chalk.bold(`  ${PLUGIN_GROUP_TITLES[group.label] ?? group.label}`));
+        lines.push('  ' + group.items.map((s) => colorFn(s)).join(chalk.gray(', ')));
     }
     if (targets.length > 0) {
         lines.push('');

package/dist/commands/prune.js

@@ -26,7 +26,7 @@ import chalk from 'chalk';
 import { confirm } from '@inquirer/prompts';
 import { diffVersionCommands, iterCommandsCapableVersions, removeCommandFromVersion, } from '../lib/commands.js';
 import { diffVersionSkills, iterSkillsCapableVersions, removeSkillFromVersion, } from '../lib/skills.js';
-import { diffVersionHooks, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
+import { listUnmanagedHooksInVersionHome, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
 import { diffVersionPlugins, iterPluginsCapableVersions, removePluginSkillFromVersion, } from '../lib/plugins.js';
 import { diffVersionSubagents, iterSubagentsCapableVersions, removeSubagentFromVersion, } from '../lib/subagents.js';
 import { getGlobalDefault } from '../lib/versions.js';
@@ -64,9 +64,12 @@ function collectOrphans(types, all) {
     }
     if (types.includes('hooks')) {
         for (const { agent, version } of scopePairs(iterHooksCapableVersions(), all)) {
-            const diff = diffVersionHooks(agent, version);
-            if (diff.orphans.length > 0) {
-                groups.push({ type: 'hooks', agent, version, orphans: diff.orphans });
+            // Orphan hooks = scripts present in the version home that no
+            // agents.yaml/hooks.yaml entry registers, so they never fire. Same
+            // definition the doctor overview reports.
+            const orphans = listUnmanagedHooksInVersionHome(agent, version);
+            if (orphans.length > 0) {
+                groups.push({ type: 'hooks', agent, version, orphans });
             }
         }
     }
@@ -210,7 +213,7 @@ async function runOrphanPrune(resourceTypes, options) {
         return;
     }
     const total = groups.reduce((n, g) => n + g.orphans.length, 0);
-    console.log(chalk.bold('Orphans (in version home, not in any source)\n'));
+    console.log(chalk.bold('Orphans (in version home, unmanaged by any source)\n'));
     for (const g of groups) {
         const label = `${g.type} · ${g.agent}@${g.version}`;
         console.log(`  ${chalk.cyan(label)}  ${g.orphans.join(', ')}`);

package/dist/commands/sync.js

@@ -61,7 +61,7 @@ async function runSync(agentSpec, opts) {
             return;
         }
         agentId = parsed.agent;
-        if (parsed.version !== 'latest')
+        if (parsed.version !== 'latest' && parsed.version !== 'oldest')
             version = parsed.version;
     }
     if (opts.agent) {

package/dist/commands/teams.js

@@ -25,6 +25,7 @@ const AGENT_NAMES = {
     grok: 'Grok',
     antigravity: 'Antigravity',
     kimi: 'Kimi',
+    droid: 'Droid',
 };
 const VALID_AGENTS = Object.keys(AGENT_NAMES);
 // 'full' kept as historical alias for 'skip'; normalized to 'skip' downstream.

package/dist/commands/trash.d.ts

@@ -7,4 +7,15 @@
  * `rm -rf ~/.agents/.history/trash/` removes bytes from disk.
  */
 import type { Command } from 'commander';
+/**
+ * Restore a soft-deleted version back into ~/.agents/.history/versions/.
+ * Shared by `agents trash restore` and the top-level `agents restore` alias.
+ * Exits the process with a non-zero code on any failure.
+ */
+export declare function restoreVersion(target: string): void;
+/**
+ * Register the top-level `agents restore` command — a shorthand for
+ * `agents trash restore` so users can undo a `remove`/`prune` directly.
+ */
+export declare function registerRestoreCommand(program: Command): void;
 export declare function registerTrashCommands(program: Command): void;

package/dist/commands/trash.js

@@ -110,6 +110,61 @@ function humanSize(bytes) {
         return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
     return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
 }
+/**
+ * Restore a soft-deleted version back into ~/.agents/.history/versions/.
+ * Shared by `agents trash restore` and the top-level `agents restore` alias.
+ * Exits the process with a non-zero code on any failure.
+ */
+export function restoreVersion(target) {
+    const parsed = parseAgentVersion(target);
+    if (!parsed) {
+        console.error(chalk.red(`Expected <agent>@<version>, got: ${target}`));
+        process.exit(1);
+    }
+    const { agent, version } = parsed;
+    const entries = listTrashEntries(agent);
+    const entry = pickLatest(entries, agent, version);
+    if (!entry) {
+        console.error(chalk.red(`No trashed copy found for ${agent}@${version}`));
+        console.error(chalk.gray('Run `agents trash list` to see what exists.'));
+        process.exit(1);
+    }
+    const dest = getVersionDir(agent, version);
+    if (fs.existsSync(dest)) {
+        console.error(chalk.red(`Cannot restore: ${dest} already exists.`));
+        console.error(chalk.gray('Move or remove the existing dir first, then re-run restore.'));
+        process.exit(1);
+    }
+    try {
+        fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+        fs.renameSync(entry.trashPath, dest);
+    }
+    catch (err) {
+        console.error(chalk.red(`Restore failed: ${err.message}`));
+        process.exit(1);
+    }
+    // Best-effort cleanup of empty stamp/version parents in trash.
+    try {
+        const verDir = path.dirname(entry.trashPath);
+        if (fs.readdirSync(verDir).length === 0)
+            fs.rmdirSync(verDir);
+        const agentDir = path.dirname(verDir);
+        if (fs.readdirSync(agentDir).length === 0)
+            fs.rmdirSync(agentDir);
+    }
+    catch { /* best-effort */ }
+    console.log(chalk.green(`Restored ${agentLabel(agent)}@${version} to ${dest}`));
+}
+/**
+ * Register the top-level `agents restore` command — a shorthand for
+ * `agents trash restore` so users can undo a `remove`/`prune` directly.
+ */
+export function registerRestoreCommand(program) {
+    program
+        .command('restore <target>')
+        .description('Restore a soft-deleted agent version (e.g. "codex@0.141.0") removed via prune/remove')
+        .action((target) => restoreVersion(target));
+}
 export function registerTrashCommands(program) {
     const trash = program
         .command('trash')
@@ -139,49 +194,10 @@ export function registerTrashCommands(program) {
                 chalk.gray(`${e.stamp}  ${size}  ${e.trashPath}`));
         }
         console.log();
-        console.log(chalk.gray('Restore with: agents trash restore <agent>@<version>'));
+        console.log(chalk.gray('Restore with: agents restore <agent>@<version>'));
     });
     trash
         .command('restore <target>')
         .description('Restore a soft-deleted version (e.g. "claude@2.1.110") back to ~/.agents/.history/versions/')
-        .action((target) => {
-        const parsed = parseAgentVersion(target);
-        if (!parsed) {
-            console.error(chalk.red(`Expected <agent>@<version>, got: ${target}`));
-            process.exit(1);
-        }
-        const { agent, version } = parsed;
-        const entries = listTrashEntries(agent);
-        const entry = pickLatest(entries, agent, version);
-        if (!entry) {
-            console.error(chalk.red(`No trashed copy found for ${agent}@${version}`));
-            console.error(chalk.gray('Run `agents trash list` to see what exists.'));
-            process.exit(1);
-        }
-        const dest = getVersionDir(agent, version);
-        if (fs.existsSync(dest)) {
-            console.error(chalk.red(`Cannot restore: ${dest} already exists.`));
-            console.error(chalk.gray('Move or remove the existing dir first, then re-run restore.'));
-            process.exit(1);
-        }
-        try {
-            fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
-            fs.renameSync(entry.trashPath, dest);
-        }
-        catch (err) {
-            console.error(chalk.red(`Restore failed: ${err.message}`));
-            process.exit(1);
-        }
-        // Best-effort cleanup of empty stamp/version parents in trash.
-        try {
-            const verDir = path.dirname(entry.trashPath);
-            if (fs.readdirSync(verDir).length === 0)
-                fs.rmdirSync(verDir);
-            const agentDir = path.dirname(verDir);
-            if (fs.readdirSync(agentDir).length === 0)
-                fs.rmdirSync(agentDir);
-        }
-        catch { /* best-effort */ }
-        console.log(chalk.green(`Restored ${agentLabel(agent)}@${version} to ${dest}`));
-    });
+        .action((target) => restoreVersion(target));
 }

package/dist/commands/versions.js

@@ -7,7 +7,8 @@ import { AGENTS, ALL_AGENT_IDS, getAccountEmail, getAccountInfo, agentLabel, } f
 import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { viewAction } from './view.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
-import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
+import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, isOldestInstalled, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
+import { carryForwardSettings } from '../lib/settings-manifest.js';
 import { createShim, createVersionedAlias, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
 import { tryAutoPull } from '../lib/git.js';
@@ -28,17 +29,6 @@ function fixSessionFilePaths(agent, version, oldVersionDir) {
     const trashPath = path.join(trashAgentDir, stamps[0]);
     updateSessionFilePaths(oldVersionDir, trashPath);
 }
-/**
- * Helper to get actual installed version for an agent.
- * Returns the latest installed version, or throws if none installed.
- */
-async function getInstalledVersionForAgent(agent) {
-    const versions = listInstalledVersions(agent);
-    if (versions.length > 0) {
-        return versions[versions.length - 1];
-    }
-    throw new Error(`No versions of ${agent} installed`);
-}
 function formatAccountHint(info, usage) {
     const parts = [];
     if (info.email)
@@ -91,7 +81,17 @@ function warnIfShimShadowed(agent) {
     }
     console.log(chalk.yellow(`  Warning: ${AGENTS[agent].cliCommand} currently resolves to ${shadowedBy}`));
     console.log(chalk.gray(`  Managed shim: ${getShimPath(agent)}`));
-    console.log(chalk.gray(`  ${getPathSetupInstructions().split('\n').join('\n  ')}`));
+    const result = addShimsToPath();
+    if (!result.success) {
+        console.log(chalk.gray(`  ${getPathSetupInstructions().split('\n').join('\n  ')}`));
+        return;
+    }
+    if (result.alreadyPresent) {
+        console.log(chalk.gray(`  Shim PATH entry already set — ${AGENTS[agent].cliCommand} is shadowed by another binary. Remove or reorder it so ${getShimPath(agent)} takes priority.`));
+        return;
+    }
+    console.log(chalk.green(`  Added shim directory to ${result.location}.`));
+    console.log(chalk.gray(`  ${result.reloadHint}`));
 }
 async function versionPruneAction(specs, options, commandName) {
     const isProject = options.project;
@@ -105,7 +105,7 @@ async function versionPruneAction(specs, options, commandName) {
         }
         const { agent, version } = parsed;
         const agentConfig = AGENTS[agent];
-        if (version === 'latest' || !spec.includes('@')) {
+        if (version === 'latest' || version === 'oldest' || !spec.includes('@')) {
             const versions = listInstalledVersions(agent);
             if (versions.length === 0) {
                 console.log(chalk.gray(`No versions of ${agentLabel(agentConfig.id)} installed`));
@@ -139,7 +139,11 @@ async function versionPruneAction(specs, options, commandName) {
                 }
                 for (const v of toRemove) {
                     const versionDir = getVersionDir(agent, v);
-                    removeVersion(agent, v);
+                    const removed = removeVersion(agent, v);
+                    if (!removed) {
+                        console.log(chalk.red(`Failed to move ${agentLabel(agentConfig.id)}@${v} to trash — a file may be locked by a running process. Close any active sessions and try again.`));
+                        continue;
+                    }
                     fixSessionFilePaths(agent, v, versionDir);
                     console.log(chalk.green(`Moved ${agentLabel(agentConfig.id)}@${v} to trash`));
                     moved.push({ agent, version: v });
@@ -166,7 +170,11 @@ async function versionPruneAction(specs, options, commandName) {
         }
         else {
             const versionDir = getVersionDir(agent, version);
-            removeVersion(agent, version);
+            const removed = removeVersion(agent, version);
+            if (!removed) {
+                console.log(chalk.red(`Failed to move ${agentLabel(agentConfig.id)}@${version} to trash — a file may be locked by a running process. Close any active sessions and try again.`));
+                continue;
+            }
             fixSessionFilePaths(agent, version, versionDir);
             console.log(chalk.green(`Moved ${agentLabel(agentConfig.id)}@${version} to trash`));
             moved.push({ agent, version });
@@ -228,6 +236,9 @@ export function registerVersionsCommands(program) {
       # Install the latest version of an agent
       agents add claude@latest
 
+      # Install the oldest published version of an agent
+      agents add claude@oldest
+
       # Install a specific version (reproducibility)
       agents add claude@2.1.112
 
@@ -259,7 +270,7 @@ export function registerVersionsCommands(program) {
                 console.log(chalk.yellow(`${agentLabel(agentConfig.id)} has no npm package. Install manually.`));
                 continue;
             }
-            // Check if already installed (handle 'latest' specially)
+            // Check if already installed (resolve 'latest'/'oldest' against npm first)
             let alreadyInstalled = false;
             let installedAsVersion = version;
             if (version === 'latest') {
@@ -269,6 +280,13 @@ export function registerVersionsCommands(program) {
                     installedAsVersion = latestCheck.version;
                 }
             }
+            else if (version === 'oldest') {
+                const oldestCheck = await isOldestInstalled(agent);
+                if (oldestCheck.installed && oldestCheck.version) {
+                    alreadyInstalled = true;
+                    installedAsVersion = oldestCheck.version;
+                }
+            }
             else {
                 alreadyInstalled = isVersionInstalled(agent, version);
             }
@@ -290,6 +308,19 @@ export function registerVersionsCommands(program) {
                         console.log(chalk.gray(`  Created shim: ${getShimsDir()}/${agentConfig.cliCommand}`));
                     }
                     const installedVersion = result.installedVersion || version;
+                    // Track the concrete version so a `--project` pin records it instead
+                    // of the `latest`/`oldest` alias.
+                    installedAsVersion = installedVersion;
+                    // Seed the fresh version home with user settings from the current
+                    // default version (settings.json, keybindings, codex config/auth).
+                    // Gap-filling only — never overwrites what the new home has.
+                    const carrySource = getGlobalDefault(agent);
+                    if (carrySource && carrySource !== installedVersion) {
+                        const carried = carryForwardSettings(agent, getVersionHomePath(agent, carrySource), getVersionHomePath(agent, installedVersion));
+                        if (carried.applied.length > 0) {
+                            console.log(chalk.gray(`  Carried settings from ${agent}@${carrySource}: ${carried.applied.map(r => path.basename(r)).join(', ')}`));
+                        }
+                    }
                     // Smart resource detection: compare available vs ACTUALLY synced (source of truth: files)
                     const available = getAvailableResources();
                     const actuallySynced = getActuallySyncedResources(agent, installedVersion);
@@ -428,14 +459,19 @@ export function registerVersionsCommands(program) {
                     ? readManifest(process.cwd()) || createDefaultManifest()
                     : createDefaultManifest();
                 manifest.agents = manifest.agents || {};
-                manifest.agents[agent] = version === 'latest' ? (await getInstalledVersionForAgent(agent)) : version;
+                manifest.agents[agent] = (version === 'latest' || version === 'oldest')
+                    ? installedAsVersion
+                    : version;
                 writeManifest(process.cwd(), manifest);
                 console.log(chalk.green(`  Pinned ${agentLabel(agentConfig.id)}@${version} in .agents/agents.yaml`));
             }
         }
     });
     configureVersionPruneCommand(program.command('prune <specs...>'), 'prune');
-    configureVersionPruneCommand(program.command('remove <specs...>', { hidden: true }), 'remove');
+    // `rm` and `purge` are commander aliases for `remove` (which is itself an
+    // alias for `prune`). Native `.aliases()` keeps them in lockstep — same
+    // action, same options, no duplicate registration.
+    configureVersionPruneCommand(program.command('remove <specs...>', { hidden: true }).aliases(['rm', 'purge']), 'remove');
     const useCmd = program
         .command('use <agent> [version]')
         .description('Switch the active version for an agent. This is the only command that sets the default.')
@@ -478,7 +514,7 @@ export function registerVersionsCommands(program) {
                     return;
                 }
                 agent = parsed.agent;
-                version = parsed.version === 'latest' ? undefined : parsed.version;
+                version = (parsed.version === 'latest' || parsed.version === 'oldest') ? undefined : parsed.version;
             }
             else {
                 const agentLower = agentArg.toLowerCase();
@@ -679,6 +715,18 @@ export function registerVersionsCommands(program) {
                     }
                 }
                 const previousDefault = getGlobalDefault(agentId);
+                // Carry user settings from the outgoing default into the target
+                // version home before switching. Gap-filling only, so versions that
+                // already have their own settings are left untouched.
+                if (previousDefault && previousDefault !== finalVersion) {
+                    const carried = carryForwardSettings(agentId, getVersionHomePath(agentId, previousDefault), getVersionHomePath(agentId, finalVersion));
+                    if (carried.applied.length > 0) {
+                        console.log(chalk.gray(`Carried settings from ${agentId}@${previousDefault}: ${carried.applied.map(r => path.basename(r)).join(', ')}`));
+                        if (carried.backupDir) {
+                            console.log(chalk.gray(`  Pre-merge backup: ${carried.backupDir}`));
+                        }
+                    }
+                }
                 // Set global default
                 setGlobalDefault(agentId, finalVersion);
                 // Regenerate shim so it uses the latest script format

package/dist/commands/view.d.ts

@@ -19,6 +19,7 @@ export interface ViewSectionFilter {
     rules?: boolean;
     hooks?: boolean;
     promptcuts?: boolean;
+    cli?: boolean;
 }
 /** Machine-readable entry for a single installed version. */
 export interface ViewJsonVersion {

package/dist/commands/view.js

@@ -6,8 +6,9 @@ import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentNam
 import { formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, } from '../lib/versions.js';
-import { getShimsDir, isShimsInPath, ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
+import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
+import { listCliStatus } from '../lib/cli-resources.js';
 import { isCapable } from '../lib/capabilities.js';
 import { discoverPlugins, pluginSupportsAgent } from '../lib/plugins.js';
 import { getAgentsDir, getUserAgentsDir, getEffectivePromptcutsPath, readMergedPromptcuts } from '../lib/state.js';
@@ -114,7 +115,7 @@ function getProjectVersionFromCwd(agent) {
         return null;
     }
 }
-const SECTION_KEYS = ['commands', 'skills', 'mcp', 'workflows', 'plugins', 'rules', 'hooks', 'promptcuts'];
+const SECTION_KEYS = ['commands', 'skills', 'mcp', 'workflows', 'plugins', 'rules', 'hooks', 'promptcuts', 'cli'];
 /**
  * Decide whether a section should render given the filter. If no flags are set,
  * everything renders (current behavior). If any flag is set, only those sections
@@ -167,6 +168,51 @@ function renderProfilesSection(profiles) {
  * Show installed versions for one or all agents.
  * Called when: `agents view` or `agents view claude`
  */
+/** Color the source-layer tag for a host CLI, matching the rules-section convention. */
+function hostCliSourceTag(source) {
+    if (source === 'project')
+        return chalk.blue('[project]');
+    if (source === 'user')
+        return chalk.cyan('[user]');
+    if (source === 'system')
+        return chalk.gray('[system]');
+    // Anything else is an extra repo, tagged by its alias.
+    return chalk.magenta(`[${source}]`);
+}
+/**
+ * Render the host-CLI section. Host CLIs are host-global: declared in any
+ * DotAgents repo's `cli/` (project > user > system > extras), installed to PATH
+ * rather than copied into a version home. They render identically in the overview
+ * and in a per-agent detail view because every agent on the host shares them.
+ * The source tag shows which repo layer declared each — so user-level and
+ * extra-repo manifests are visibly supported.
+ */
+function renderHostClisSection(cwd) {
+    const { statuses, errors } = listCliStatus(cwd);
+    console.log(chalk.bold('\nHost CLIs\n'));
+    if (statuses.length === 0) {
+        console.log(`  ${chalk.gray('none declared')} ${chalk.gray('— add one with `agents cli add <name>`')}`);
+    }
+    else {
+        const nameWidth = Math.max(...statuses.map((s) => s.manifest.name.length));
+        let anyMissing = false;
+        for (const { manifest, installed } of statuses) {
+            if (!installed)
+                anyMissing = true;
+            const status = installed ? chalk.green('installed') : chalk.red('missing  ');
+            const linkedName = termLink(manifest.name.padEnd(nameWidth), linkTarget(manifest.path));
+            const tag = hostCliSourceTag(manifest.source);
+            const desc = manifest.description ? chalk.gray(`  ${summarizeDescription(manifest.description, 60)}`) : '';
+            console.log(`  ${status}  ${chalk.cyan(linkedName)} ${tag}${desc}`);
+        }
+        if (anyMissing) {
+            console.log(chalk.gray('  Install missing with `agents cli install`'));
+        }
+    }
+    for (const err of errors) {
+        console.log(`  ${chalk.red('error')}      ${chalk.gray(err.file)}: ${chalk.gray(err.reason)}`);
+    }
+}
 async function showInstalledVersions(filterAgentId) {
     const spinnerText = filterAgentId
         ? `Checking ${agentLabel(filterAgentId)} agents...`
@@ -537,16 +583,9 @@ async function showInstalledVersions(filterAgentId) {
         console.log(chalk.gray('  Run: agents add claude@latest'));
         console.log();
     }
-    // Show shims path status at the end (only for full list with managed versions)
-    if (versionManaged.length > 0 && !filterAgentId) {
-        const shimsDir = getShimsDir();
-        if (isShimsInPath()) {
-            console.log(chalk.gray(`Shims: ${shimsDir} (in PATH)`));
-        }
-        else {
-            console.log(chalk.yellow(`Shims: ${shimsDir} (not in PATH)`));
-            console.log(chalk.gray('Add to PATH for automatic version switching'));
-        }
+    // Host CLIs are host-global, not per-agent — show them once in the overview.
+    if (!filterAgentId) {
+        renderHostClisSection(process.cwd());
     }
     // Check for new resources when viewing a specific agent
     if (filterAgentId && versionManaged.length > 0) {
@@ -903,6 +942,9 @@ async function showAgentResources(agentId, requestedVersion, filter) {
     if (shouldRenderSection('promptcuts', filter)) {
         renderPromptcuts();
     }
+    if (shouldRenderSection('cli', filter)) {
+        renderHostClisSection(cwd);
+    }
     // Show legend at the end if git repo exists and we showed all sections.
     // Filtered single-section views skip it — noise for promptcuts or plugins.
     if (hasGitRepo && !anyFilterSet) {
@@ -1194,6 +1236,7 @@ export async function viewAction(agentArg, options) {
         rules: options?.rules,
         hooks: options?.hooks,
         promptcuts: options?.promptcuts,
+        cli: options?.cli,
     };
     const filterIsSet = SECTION_KEYS.some((k) => filter[k]);
     if (!agentArg) {
@@ -1274,6 +1317,7 @@ export function registerViewCommand(program) {
         .option('--rules', 'Show only rules in the detail view.')
         .option('--hooks', 'Show only hooks in the detail view.')
         .option('--promptcuts', 'Show only promptcuts in the detail view.')
+        .option('--cli', 'Show only host CLIs (declared in cli/, installed to PATH).')
         .addHelpText('after', `
 Examples:
   # Show all installed agents with versions, accounts, and usage