@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/lib/versions.js

@@ -23,9 +23,9 @@ import { promisify } from 'util';
 import chalk from 'chalk';
 import * as TOML from 'smol-toml';
 import { checkbox, select } from '@inquirer/prompts';
-import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, clearVersionResources, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset } from './state.js';
+import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset } from './state.js';
 import { defaultPatterns, expandPatterns } from './resource-patterns.js';
-import { resolveResource, listResources } from './resources.js';
+import { listResources } from './resources.js';
 import { AGENTS, getAccountEmail, MCP_CAPABLE_AGENTS, COMMANDS_CAPABLE_AGENTS, getMcpConfigPathForHome, parseMcpConfig, resolveAgentName, formatAgentError } from './agents.js';
 import { applyPermissionsToVersion as applyPermsToVersion, PERMISSIONS_CAPABLE_AGENTS, discoverPermissionGroups, buildPermissionsFromGroups, CODEX_RULES_FILENAME, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.js';
 import { installMcpServers, parseMcpServerConfig } from './mcp.js';
@@ -296,13 +296,21 @@ export function getActuallySyncedResources(agent, version, options = {}) {
         workflows: [],
         promptcuts: false,
     };
-    // Commands - check what files exist in version home
-    const commandsDir = path.join(configDir, agentConfig.commandsSubdir);
-    if (fs.existsSync(commandsDir)) {
-        const ext = agentConfig.format === 'toml' ? '.toml' : '.md';
-        result.commands = fs.readdirSync(commandsDir)
-            .filter(f => f.endsWith(ext))
-            .map(f => f.replace(new RegExp(`\\${ext}$`), ''));
+    // Commands - check what files exist in version home.
+    // For agent/version pairs that store commands as converted skills (e.g. Codex >= 0.117.0),
+    // detect them via the agents_command marker in skills/<name>/SKILL.md — otherwise the
+    // diff falsely reports every command as "new" every run and re-prompts on `agents view`.
+    if (shouldInstallCommandAsSkill(agent, version)) {
+        result.commands = listCommandSkillsInVersion(path.join(configDir));
+    }
+    else {
+        const commandsDir = path.join(configDir, agentConfig.commandsSubdir);
+        if (fs.existsSync(commandsDir)) {
+            const ext = agentConfig.format === 'toml' ? '.toml' : '.md';
+            result.commands = fs.readdirSync(commandsDir)
+                .filter(f => f.endsWith(ext))
+                .map(f => f.replace(new RegExp(`\\${ext}$`), ''));
+        }
     }
     // Skills - check what directories exist AND content matches central source
     const skillsDir = path.join(configDir, 'skills');
@@ -503,16 +511,130 @@ export function getActuallySyncedResources(agent, version, options = {}) {
     }
     return result;
 }
+/**
+ * Names that exist ONLY in the project's `.agents/` layer (no matching entry in
+ * user/system/extra layers). Sync intentionally skips project-layer commands,
+ * skills, hooks, subagents, plugins, and workflows for security — see the
+ * defense comments above each sync branch in syncResourcesToVersion. Without
+ * this filter, those names would forever appear in the "New resources" diff
+ * because they live in `available` but never reach `actuallySynced`.
+ */
+export function getProjectOnlyResources(cwd = process.cwd()) {
+    const empty = {
+        commands: new Set(), skills: new Set(), hooks: new Set(),
+        subagents: new Set(), plugins: new Set(), workflows: new Set(),
+    };
+    const projectAgentsDir = getProjectAgentsDir(cwd);
+    if (!projectAgentsDir)
+        return empty;
+    const trustedBases = [getUserAgentsDir(), getAgentsDir(), ...getEnabledExtraRepos().map(e => e.dir)];
+    const trustedNames = (relSubdir, predicate) => {
+        const acc = new Set();
+        for (const base of trustedBases) {
+            const dir = path.join(base, relSubdir);
+            if (!fs.existsSync(dir))
+                continue;
+            try {
+                for (const entry of fs.readdirSync(dir)) {
+                    if (entry.startsWith('.'))
+                        continue;
+                    if (predicate(path.join(dir, entry), entry))
+                        acc.add(entry);
+                }
+            }
+            catch { /* ignore unreadable */ }
+        }
+        return acc;
+    };
+    const readProjectNames = (relSubdir, predicate) => {
+        const dir = path.join(projectAgentsDir, relSubdir);
+        if (!fs.existsSync(dir))
+            return [];
+        try {
+            return fs.readdirSync(dir)
+                .filter(e => !e.startsWith('.'))
+                .filter(e => predicate(path.join(dir, e), e));
+        }
+        catch {
+            return [];
+        }
+    };
+    const isMdFile = (full, name) => name.endsWith('.md') && (() => { try {
+        return fs.statSync(full).isFile();
+    }
+    catch {
+        return false;
+    } })();
+    const isDir = (full) => { try {
+        return fs.statSync(full).isDirectory();
+    }
+    catch {
+        return false;
+    } };
+    const hasFile = (sub) => (full) => isDir(full) && fs.existsSync(path.join(full, sub));
+    const stripMd = (n) => n.replace(/\.md$/, '');
+    const trustedCommands = new Set([...trustedNames('commands', isMdFile)].map(stripMd));
+    const projectCommands = readProjectNames('commands', isMdFile).map(stripMd);
+    for (const n of projectCommands)
+        if (!trustedCommands.has(n))
+            empty.commands.add(n);
+    const trustedSkills = trustedNames('skills', (full) => isDir(full));
+    for (const n of readProjectNames('skills', (full) => isDir(full)))
+        if (!trustedSkills.has(n))
+            empty.skills.add(n);
+    // Hooks: project entries are files; trusted entries are also files. Name match
+    // is filename-with-extension (sync compares by full filename, line 2031).
+    const trustedHooks = trustedNames('hooks', (full) => { try {
+        return fs.statSync(full).isFile();
+    }
+    catch {
+        return false;
+    } });
+    for (const n of readProjectNames('hooks', (full) => { try {
+        return fs.statSync(full).isFile();
+    }
+    catch {
+        return false;
+    } })) {
+        if (!trustedHooks.has(n))
+            empty.hooks.add(n);
+    }
+    const trustedSubagents = trustedNames('subagents', hasFile('AGENT.md'));
+    for (const n of readProjectNames('subagents', hasFile('AGENT.md'))) {
+        if (!trustedSubagents.has(n))
+            empty.subagents.add(n);
+    }
+    const trustedWorkflows = trustedNames('workflows', hasFile('WORKFLOW.md'));
+    for (const n of readProjectNames('workflows', hasFile('WORKFLOW.md'))) {
+        if (!trustedWorkflows.has(n))
+            empty.workflows.add(n);
+    }
+    const trustedPlugins = trustedNames('plugins', hasFile('.claude-plugin/plugin.json'));
+    for (const n of readProjectNames('plugins', hasFile('.claude-plugin/plugin.json'))) {
+        if (!trustedPlugins.has(n))
+            empty.plugins.add(n);
+    }
+    return empty;
+}
 /**
  * Compare available resources with what's ACTUALLY synced to version home.
  * Returns only NEW resources that haven't been synced yet.
  * Source of truth: the actual files/config, NOT agents.yaml tracking.
+ *
+ * `projectOnly` (recommended): the result of `getProjectOnlyResources(cwd)`.
+ * Names listed there are filtered out for kinds that sync intentionally
+ * excludes the project layer — otherwise they would re-appear as "new"
+ * on every run and "Yes, sync all new" would silently do nothing for them.
  */
-export function getNewResources(available, actuallySynced) {
+export function getNewResources(available, actuallySynced, projectOnly) {
+    const exclude = projectOnly || {
+        commands: new Set(), skills: new Set(), hooks: new Set(),
+        subagents: new Set(), plugins: new Set(), workflows: new Set(),
+    };
     return {
-        commands: available.commands.filter(c => !actuallySynced.commands.includes(c)),
-        skills: available.skills.filter(s => !actuallySynced.skills.includes(s)),
-        hooks: available.hooks.filter(h => !actuallySynced.hooks.includes(h)),
+        commands: available.commands.filter(c => !actuallySynced.commands.includes(c) && !exclude.commands.has(c)),
+        skills: available.skills.filter(s => !actuallySynced.skills.includes(s) && !exclude.skills.has(s)),
+        hooks: available.hooks.filter(h => !actuallySynced.hooks.includes(h) && !exclude.hooks.has(h)),
         // Memory/rules presets are mutually exclusive — only one can be active.
         // If any preset is synced, don't report others as "new".
         memory: actuallySynced.memory.length > 0
@@ -520,9 +642,9 @@ export function getNewResources(available, actuallySynced) {
             : available.memory.filter(m => !actuallySynced.memory.includes(m)),
         mcp: available.mcp.filter(m => !actuallySynced.mcp.includes(m)),
         permissions: available.permissions.filter(p => !actuallySynced.permissions.includes(p)),
-        subagents: available.subagents.filter(s => !actuallySynced.subagents.includes(s)),
-        plugins: available.plugins.filter(p => !actuallySynced.plugins.includes(p)),
-        workflows: available.workflows.filter(w => !actuallySynced.workflows.includes(w)),
+        subagents: available.subagents.filter(s => !actuallySynced.subagents.includes(s) && !exclude.subagents.has(s)),
+        plugins: available.plugins.filter(p => !actuallySynced.plugins.includes(p) && !exclude.plugins.has(p)),
+        workflows: available.workflows.filter(w => !actuallySynced.workflows.includes(w) && !exclude.workflows.has(w)),
         // Promptcuts aren't version-scoped — the hook reads ~/.agents/promptcuts.yaml
         // directly, so there is never a "new" per-version state to reconcile.
         promptcuts: false,
@@ -554,10 +676,15 @@ export function hasNewResources(diff, agent, version) {
  * Build a summary string of new resources.
  * E.g., "2 commands, 5 permission groups"
  */
-function buildNewResourcesSummary(newResources, agent) {
+function buildNewResourcesSummary(newResources, agent, version) {
     const agentConfig = AGENTS[agent];
     const parts = [];
-    if (newResources.commands.length > 0 && COMMANDS_CAPABLE_AGENTS.includes(agent)) {
+    // Use version-aware gates so Codex >= 0.117.0 (which converts commands to skills) doesn't
+    // double-count and so "16 commands" never appears in the summary when commands have
+    // already been emitted as skills in the version home.
+    const commandsApply = version ? supports(agent, 'commands', version).ok : COMMANDS_CAPABLE_AGENTS.includes(agent);
+    const commandsAsSkills = version ? shouldInstallCommandAsSkill(agent, version) : false;
+    if (newResources.commands.length > 0 && (commandsApply || commandsAsSkills)) {
         parts.push(`${newResources.commands.length} command${newResources.commands.length === 1 ? '' : 's'}`);
     }
     if (newResources.skills.length > 0) {
@@ -566,7 +693,7 @@ function buildNewResourcesSummary(newResources, agent) {
     if (newResources.hooks.length > 0 && agentConfig.supportsHooks) {
         parts.push(`${newResources.hooks.length} hook${newResources.hooks.length === 1 ? '' : 's'}`);
     }
-    if (newResources.memory.length > 0 && COMMANDS_CAPABLE_AGENTS.includes(agent)) {
+    if (newResources.memory.length > 0 && (commandsApply || commandsAsSkills)) {
         parts.push(`${newResources.memory.length} rule file${newResources.memory.length === 1 ? '' : 's'}`);
     }
     if (newResources.mcp.length > 0 && MCP_CAPABLE_AGENTS.includes(agent)) {
@@ -590,15 +717,21 @@ function buildNewResourcesSummary(newResources, agent) {
  * Prompt user to select which NEW resources to sync.
  * Only shows resources that haven't been synced yet.
  */
-export async function promptNewResourceSelection(agent, newResources) {
+export async function promptNewResourceSelection(agent, newResources, version) {
     const agentConfig = AGENTS[agent];
     const selection = {};
+    // Version-aware gates. When version is known, prefer per-version capability checks; the
+    // commands branch is allowed when either native commands are supported OR when the
+    // version emits commands as converted skills (Codex >= 0.117.0).
+    const commandsApply = version ? supports(agent, 'commands', version).ok : COMMANDS_CAPABLE_AGENTS.includes(agent);
+    const commandsAsSkills = version ? shouldInstallCommandAsSkill(agent, version) : false;
+    const commandsBranch = commandsApply || commandsAsSkills;
     // Get permission group info for display
     const permissionGroups = discoverPermissionGroups();
     const newPermissionGroups = permissionGroups.filter(g => newResources.permissions.includes(g.name));
     const totalNewPermissionRules = newPermissionGroups.reduce((sum, g) => sum + g.ruleCount, 0);
     // Build the summary
-    const summary = buildNewResourcesSummary(newResources, agent);
+    const summary = buildNewResourcesSummary(newResources, agent, version);
     console.log(chalk.cyan(`\nNew resources available:`));
     console.log(chalk.gray(`  ${summary}`));
     // Ask how to handle new resources
@@ -616,13 +749,13 @@ export async function promptNewResourceSelection(agent, newResources) {
     }
     if (action === 'all') {
         // Sync all new resources
-        if (newResources.commands.length > 0 && COMMANDS_CAPABLE_AGENTS.includes(agent))
+        if (newResources.commands.length > 0 && commandsBranch)
             selection.commands = newResources.commands;
         if (newResources.skills.length > 0)
             selection.skills = newResources.skills;
         if (newResources.hooks.length > 0 && agentConfig.supportsHooks)
             selection.hooks = newResources.hooks;
-        if (newResources.memory.length > 0 && COMMANDS_CAPABLE_AGENTS.includes(agent))
+        if (newResources.memory.length > 0 && commandsBranch)
             selection.memory = newResources.memory;
         if (newResources.mcp.length > 0 && MCP_CAPABLE_AGENTS.includes(agent))
             selection.mcp = newResources.mcp;
@@ -637,7 +770,7 @@ export async function promptNewResourceSelection(agent, newResources) {
         return selection;
     }
     // Select specific items for each category
-    if (newResources.commands.length > 0 && COMMANDS_CAPABLE_AGENTS.includes(agent)) {
+    if (newResources.commands.length > 0 && commandsBranch) {
         const selected = await checkbox({
             message: 'Select new commands to sync:',
             choices: newResources.commands.map(c => ({ name: c, value: c, checked: true })),
@@ -661,7 +794,7 @@ export async function promptNewResourceSelection(agent, newResources) {
         if (selected.length > 0)
             selection.hooks = selected;
     }
-    if (newResources.memory.length > 0 && COMMANDS_CAPABLE_AGENTS.includes(agent)) {
+    if (newResources.memory.length > 0 && commandsBranch) {
         const selected = await checkbox({
             message: 'Select new rule files to sync:',
             choices: newResources.memory.map(m => ({ name: m, value: m, checked: true })),
@@ -873,8 +1006,26 @@ export function getVersionDir(agent, version) {
  * Get the binary path for a specific agent version.
  */
 export function getBinaryPath(agent, version) {
-    const versionDir = getVersionDir(agent, version);
     const agentConfig = AGENTS[agent];
+    if (agent === 'grok') {
+        // Grok binaries live in the global ~/.grok/downloads, not per-version node_modules.
+        // We return a best-effort path (used for display / checks). Real resolution
+        // happens in agents.ts resolveGrokBinary + the generated shims.
+        const grokDownloads = path.join(os.homedir(), '.grok', 'downloads');
+        // Best effort: first matching file for this version
+        try {
+            const entries = fs.readdirSync(grokDownloads);
+            const match = entries.find((e) => e.includes(version) && e.startsWith('grok-'));
+            if (match)
+                return path.join(grokDownloads, match);
+            const first = entries.find((e) => e.startsWith('grok-'));
+            if (first)
+                return path.join(grokDownloads, first);
+        }
+        catch { }
+        return path.join(grokDownloads, `grok-${version}`);
+    }
+    const versionDir = getVersionDir(agent, version);
     return path.join(versionDir, 'node_modules', '.bin', agentConfig.cliCommand);
 }
 /**
@@ -940,7 +1091,7 @@ export function listInstalledVersions(agent) {
  * List every version directory for an agent, including ones missing the
  * binary (typically home-only leftovers from a prior `removeVersion`).
  *
- * Used by `agents prune` to surface stale installs that the regular
+ * Used by `agents prune cleanup` to surface stale installs that the regular
  * `listInstalledVersions` filters out. Do NOT use elsewhere — every other
  * call site assumes a working binary.
  */
@@ -990,21 +1141,51 @@ export function setGlobalDefault(agent, version) {
  */
 export async function installVersion(agent, version, onProgress) {
     const agentConfig = AGENTS[agent];
-    if (!agentConfig.npmPackage) {
-        return { success: false, installedVersion: version, error: 'Agent has no npm package' };
-    }
     // Validate before deriving filesystem paths or npm package specs. The CLI
     // parser already enforces this for user input; this guard protects direct
     // callers and tests the critical install path at the source.
     if (!VERSION_RE.test(version)) {
         throw new Error(`Invalid version: ${JSON.stringify(version)}`);
     }
+    if (!agentConfig.npmPackage) {
+        if (!agentConfig.installScript) {
+            return { success: false, installedVersion: version, error: 'Agent has no npm package' };
+        }
+        if (version !== 'latest' && !agentConfig.installScript.includes('VERSION')) {
+            return {
+                success: false,
+                installedVersion: version,
+                error: `${agentConfig.name} installer does not support version-pinned installs. Use ${agent}@latest.`,
+            };
+        }
+        let installedVersion = version;
+        try {
+            const script = agentConfig.installScript.replaceAll('VERSION', version);
+            onProgress?.(`Installing ${agentConfig.name}@${version} via official installer...`);
+            await execAsync(script, { timeout: 120000 });
+            if (version === 'latest') {
+                installedVersion = await getCliVersionFromPath(agent) || version;
+            }
+            onProgress?.(`${agentConfig.name} installed. Setting up agents-cli version home for isolation...`);
+        }
+        catch (err) {
+            emit('version.install', { agent, version, error: err.message });
+            return { success: false, installedVersion: version, error: `${agentConfig.name} installer failed: ${err.message}` };
+        }
+        ensureAgentsDir();
+        const versionDir = getVersionDir(agent, installedVersion);
+        fs.mkdirSync(versionDir, { recursive: true });
+        fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
+        createVersionedAlias(agent, installedVersion);
+        emit('version.install', { agent, version: installedVersion });
+        return { success: true, installedVersion };
+    }
     ensureAgentsDir();
     const versionDir = getVersionDir(agent, version);
     // Create version directory and isolated home
     fs.mkdirSync(versionDir, { recursive: true });
     fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
-    // Initialize package.json
+    // Initialize package.json (only for real npm agents)
     const packageJson = {
         name: `agents-${agent}-${version}`,
         version: '1.0.0',
@@ -1147,8 +1328,6 @@ export function removeVersion(agent, version) {
     }
     // Remove versioned alias (e.g., claude@2.0.65)
     removeVersionedAlias(agent, version);
-    // Clear resource tracking for this version
-    clearVersionResources(agent, version);
     // Clear default if it was the removed version - user must explicitly pick a new one
     if (getGlobalDefault(agent) === version) {
         const meta = readMeta();
@@ -1175,6 +1354,23 @@ export function removeVersion(agent, version) {
     emit('version.remove', { agent, version });
     return true;
 }
+/**
+ * Print the standard footer after one or more versions were soft-deleted to
+ * trash. Reminds the user that sessions stay readable and how to restore.
+ */
+export function printTrashFooter(moved) {
+    if (moved.length === 0)
+        return;
+    console.log();
+    console.log(chalk.gray('Sessions remain accessible via `agents sessions`.'));
+    if (moved.length === 1) {
+        const { agent, version } = moved[0];
+        console.log(chalk.gray(`Restore with: agents trash restore ${agent}@${version}`));
+    }
+    else {
+        console.log(chalk.gray('Restore with: agents trash restore <agent>@<version>  (run `agents trash list` to see)'));
+    }
+}
 /**
  * Remove all versions of an agent. Preserves each version's `home/` directory
  * so conversation history is never deleted; the per-version folders (now
@@ -1320,6 +1516,18 @@ export async function getInstalledVersion(agent, version) {
         return version;
     }
 }
+async function getCliVersionFromPath(agent) {
+    const agentConfig = AGENTS[agent];
+    try {
+        await execFileAsync('which', [agentConfig.cliCommand]);
+        const { stdout } = await execFileAsync(agentConfig.cliCommand, ['--version'], { timeout: 3000 });
+        const match = stdout.match(/(\d+\.\d+\.\d+)/);
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Get the diff between central resources (~/.agents/) and what's synced to a version.
  * Uses filesystem state - no tracking needed.
@@ -1558,12 +1766,11 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             }
         }
     }
-    // Fast guard: skip the entire sync when no selection is active and nothing
-    // has changed since the last full sync. Drops steady-state cost from ~16s
-    // (unconditional file copies) to ~8-15ms (`isStale` walks the manifest's
-    // fingerprints, short-circuiting at the first mismatch). Numbers from
-    // scripts/bench-staleness.ts against a real ~50-resource project.
-    if (!selection && !options.force) {
+    // Fast guard: skip the entire sync when the caller requested a full sync and
+    // nothing has changed since the last full sync. Pattern-derived selections
+    // still count as full syncs because they are the persisted intended scope,
+    // not a one-off caller override.
+    if (!userPassedSelection && !options.force) {
         const manifest = loadManifest(agent, version);
         if (manifest && !isStale(manifest, agent, version, cwd)) {
             return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [] };
@@ -1626,13 +1833,25 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         }
         const syncedCommands = [];
         for (const cmd of commandsToSync) {
-            const resolved = resolveResource('commands', `${cmd}.md`, cwd);
-            if (!resolved || fs.lstatSync(resolved.path).isSymbolicLink())
+            // Commands are content that gets injected into the agent's prompt
+            // surface (slash commands, skill bodies). We intentionally do NOT pull
+            // from the project's own .agents/commands/ directory: a cloned public
+            // repo could ship a command whose body instructs the agent to do
+            // something harmful the next time the user invokes it. Commands must
+            // come from the user's central ~/.agents/commands/, the system layer,
+            // or an explicitly enabled extra repo. Same defense as hooks below.
+            const candidates = [
+                safeJoin(path.join(userAgentsDir, 'commands'), `${cmd}.md`),
+                safeJoin(getCommandsDir(), `${cmd}.md`),
+                ...extraRepos.map((e) => safeJoin(path.join(e.dir, 'commands'), `${cmd}.md`)),
+            ];
+            const srcFile = candidates.find((p) => p && fs.existsSync(p) && !fs.lstatSync(p).isSymbolicLink()) || null;
+            if (!srcFile)
                 continue;
-            const srcFile = resolved.path;
             if (commandsAsSkills) {
+                // Project skills dir is intentionally excluded for the same reason
+                // commands are: the body of a project skill becomes agent context.
                 const skillSourceDirs = [
-                    projectAgentsDir ? path.join(projectAgentsDir, 'skills') : null,
                     path.join(userAgentsDir, 'skills'),
                     getSkillsDir(),
                     ...extraRepos.map((e) => path.join(e.dir, 'skills')),
@@ -1653,6 +1872,30 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         }
         result.commands = syncedCommands.length > 0;
     }
+    // Orphan-sweep stale top-level command files from previous syncs under a
+    // different cwd. Only runs in "full sync" mode — i.e. when the caller did
+    // not pass an explicit `selection`. Callers that pass explicit selections
+    // are using the incremental/additive API (sync exactly these; leave others
+    // alone), so the sweep would be a contract violation there. The
+    // cross-project leak always comes from the no-selection shim auto-sync at
+    // launch.
+    if (!userPassedSelection && COMMANDS_CAPABLE_AGENTS.includes(agent) && !shouldInstallCommandAsSkill(agent, version)) {
+        const commandsTargetSweep = path.join(agentDir, agentConfig.commandsSubdir);
+        if (fs.existsSync(commandsTargetSweep)) {
+            const ext = agentConfig.format === 'toml' ? '.toml' : '.md';
+            const trustedCommands = new Set(commandsToSync);
+            for (const entry of fs.readdirSync(commandsTargetSweep, { withFileTypes: true })) {
+                if (!entry.isFile() || entry.name.startsWith('.'))
+                    continue;
+                if (!entry.name.endsWith(ext))
+                    continue;
+                const name = entry.name.slice(0, -ext.length);
+                if (!trustedCommands.has(name)) {
+                    removePath(safeJoin(commandsTargetSweep, entry.name));
+                }
+            }
+        }
+    }
     // Sync skills (skip if agent natively reads ~/.agents/skills/)
     if (agentConfig.nativeAgentsSkillsDir) {
         // Clean up stale skills symlink/dir — agent reads from ~/.agents/skills/ directly
@@ -1677,10 +1920,19 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             fs.mkdirSync(skillsTarget, { recursive: true });
             const syncedSkills = [];
             for (const skill of skillsToSync) {
-                const resolved = resolveResource('skills', skill, cwd);
-                const srcDir = resolved && fs.existsSync(resolved.path) && fs.lstatSync(resolved.path).isDirectory()
-                    ? resolved.path
-                    : null;
+                // Same defense as commands and hooks: don't pull skills from the
+                // project's .agents/skills/ directory. A skill's contents (SKILL.md
+                // and any auxiliary scripts) get loaded into the agent's tool/context
+                // surface, and a malicious public repo could ship a SKILL.md whose
+                // body coerces the agent. Trusted layers only.
+                const skillCandidates = [
+                    safeJoin(path.join(userAgentsDir, 'skills'), skill),
+                    safeJoin(getSkillsDir(), skill),
+                    ...extraRepos.map((e) => safeJoin(path.join(e.dir, 'skills'), skill)),
+                ];
+                const srcDir = skillCandidates.find((p) => fs.existsSync(p) &&
+                    !fs.lstatSync(p).isSymbolicLink() &&
+                    fs.lstatSync(p).isDirectory()) || null;
                 if (!srcDir)
                     continue;
                 const destDir = safeJoin(skillsTarget, skill);
@@ -1690,6 +1942,21 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             }
             result.skills = syncedSkills.length > 0;
         }
+        // Orphan-sweep stale skill directories from previous syncs under a
+        // different cwd. Only runs in "full sync" mode (no explicit selection) —
+        // see the matching guard on the commands sweep above for why. Skip
+        // dot-dirs to keep plugin-managed subtrees (.plugins/, .promptcuts) intact.
+        const skillsTargetSweep = path.join(agentDir, 'skills');
+        if (!userPassedSelection && fs.existsSync(skillsTargetSweep) && !fs.lstatSync(skillsTargetSweep).isSymbolicLink()) {
+            const trustedSkills = new Set(skillsToSync);
+            for (const entry of fs.readdirSync(skillsTargetSweep, { withFileTypes: true })) {
+                if (!entry.isDirectory() || entry.name.startsWith('.'))
+                    continue;
+                if (!trustedSkills.has(entry.name)) {
+                    removePath(safeJoin(skillsTargetSweep, entry.name));
+                }
+            }
+        }
     }
     // Sync hooks (if agent supports them at this version)
     const hooksGate = supports(agent, 'hooks', version);
@@ -1742,7 +2009,9 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                 result.hooks = syncedHooks.length > 0;
                 // Register hooks into agent-native settings.json/hooks.json. Gemini
                 // shipped hooks in 0.26.0; gate already passed above so this is safe.
-                if (agent === 'claude' || agent === 'codex' || agent === 'gemini') {
+                // Grok auto-discovers from ~/.grok/hooks/ so the script copy above
+                // is sufficient — no settings.json registration needed.
+                if (agent === 'claude' || agent === 'codex' || agent === 'gemini' || agent === 'antigravity') {
                     registerHooksToSettings(agent, versionHome);
                 }
             }
@@ -1781,6 +2050,10 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // ~/.agents/permissions/presets/<name>.yaml pick a subset via `includes:`.
     // If AGENTS_PERMISSION_PRESET is set, we resolve that recipe and use its
     // includes list as the group filter (intersected with groups on disk).
+    // Note: discoverPermissionGroups intentionally reads from user + system
+    // only — never from a project's .agents/permissions/. Permissions gate
+    // every other action, so a cloned public repo must not be able to widen
+    // its own sandbox by shipping a permissions group. Same defense as hooks.
     const permissionGroups = discoverPermissionGroups();
     const allGroupNames = permissionGroups.map(g => g.name);
     const activePresetName = getActivePermissionPresetName();
@@ -1825,15 +2098,30 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // Install MCP servers (if agent supports them)
     // For Claude/Codex: uses CLI commands (claude mcp add, codex mcp add)
     // For others: edits config files directly
-    const mcpToSync = selection
+    //
+    // Mirror the hooks defense: exclude project-scoped MCPs from the sync. An
+    // MCP server is an executable invoked under the agent's authority, so a
+    // cloned public repo's .agents/mcp/foo.yaml could install an arbitrary
+    // command. We pre-compute the set of project-scoped names and drop them
+    // before handing the list to installMcpServers. (The deeper helper-side
+    // dedup in lib/mcp.ts still lets a project entry shadow a same-named
+    // user entry, so name-collision shadowing is not fully closed here —
+    // tracked separately for a follow-up in lib/mcp.ts.)
+    const projectScopedMcpNames = new Set(getScopedMcpResources(cwd).filter(r => r.scope === 'project').map(r => r.name));
+    const mcpToSyncAll = selection
         ? resolveSelection(selection.mcp, available.mcp)
         : (MCP_CAPABLE_AGENTS.includes(agent) ? available.mcp : []);
+    const mcpToSync = mcpToSyncAll.filter(n => !projectScopedMcpNames.has(n));
     if (mcpToSync.length > 0 && MCP_CAPABLE_AGENTS.includes(agent)) {
         const mcpResult = installMcpServers(agent, version, versionHome, mcpToSync, { cwd });
         result.mcp = mcpResult.applied;
         // mcp patterns already written via ensureVersionResourcePatterns above.
     }
-    // Sync subagents (claude and openclaw only)
+    // Sync subagents (claude and openclaw only).
+    // Note: listInstalledSubagents (used to populate the map below) reads only
+    // user + system layers — never project. Subagents bundle prompts that fire
+    // when the agent delegates work, so a cloned public repo must not be able
+    // to plant a subagent the user later invokes. Same defense as hooks.
     const subagentsToSync = selection
         ? resolveSelection(selection.subagents, available.subagents)
         : (SUBAGENT_CAPABLE_AGENTS.includes(agent) ? available.subagents : []);
@@ -1864,6 +2152,29 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             }
             catch { /* resource sync failed for this item */ }
         }
+        // Orphan-sweep stale subagents. Same selection-mode guard as the
+        // commands/skills sweeps above. Claude stores them as flat .md files
+        // under `<agentDir>/agents/`; OpenClaw stores them as subdirs at the
+        // same level as commands/skills/hooks/plugins (no isolated parent dir),
+        // which means a directory-readdir sweep would unsafely hit unrelated
+        // resources. For OpenClaw we lean on the existing per-name copy path —
+        // if the user wants strict isolation on OpenClaw, track via manifest.
+        if (!userPassedSelection && agent === 'claude') {
+            const claudeAgentsDir = path.join(agentDir, 'agents');
+            if (fs.existsSync(claudeAgentsDir)) {
+                const trustedSubagents = new Set(subagentsToSync);
+                for (const entry of fs.readdirSync(claudeAgentsDir, { withFileTypes: true })) {
+                    if (!entry.isFile() || entry.name.startsWith('.'))
+                        continue;
+                    if (!entry.name.endsWith('.md'))
+                        continue;
+                    const name = entry.name.slice(0, -'.md'.length);
+                    if (!trustedSubagents.has(name)) {
+                        removePath(safeJoin(claudeAgentsDir, entry.name));
+                    }
+                }
+            }
+        }
         // subagent patterns already written via ensureVersionResourcePatterns above.
     }
     // Sync plugins (claude and openclaw)
@@ -1929,6 +2240,24 @@ export function getEffectiveHome(agentId) {
     }
     return os.homedir();
 }
+/**
+ * Thrown when the user references an agent@version that is not installed.
+ * Carries the parsed (agentId, version) so callers can react — e.g. prompt
+ * to install it on demand — without having to parse the error message.
+ */
+export class VersionNotInstalledError extends Error {
+    agentId;
+    version;
+    installedVersions;
+    constructor(agentId, version, installedVersions) {
+        const installed = installedVersions.length > 0 ? installedVersions.join(', ') : '(none)';
+        super(`Version ${version} is not installed for ${AGENTS[agentId].name}. Installed versions: ${installed}`);
+        this.agentId = agentId;
+        this.version = version;
+        this.installedVersions = installedVersions;
+        this.name = 'VersionNotInstalledError';
+    }
+}
 /**
  * Resolve a comma-separated --agents list into concrete version selections.
  * Bare agents target the default version, or the newest installed version when no default exists.
@@ -1938,10 +2267,26 @@ export function resolveAgentVersionTargets(value, availableAgents, options = {})
     const selectedAgents = [];
     const versionSelections = new Map();
     const explicitSelections = new Set();
-    const targets = value
+    const rawTargets = value
         .split(',')
         .map((item) => item.trim())
         .filter(Boolean);
+    // Expand literal `all` (with optional @all) into every available agent's all
+    // installed versions. Skip agents with no installed versions so `all` is
+    // lenient — only explicit `claude@all` errors when claude isn't installed.
+    const targets = [];
+    for (const t of rawTargets) {
+        if (t === 'all' || t === 'all@all') {
+            for (const a of availableAgents) {
+                if (listInstalledVersions(a).length > 0) {
+                    targets.push(`${a}@all`);
+                }
+            }
+        }
+        else {
+            targets.push(t);
+        }
+    }
     for (const target of targets) {
         const atIndex = target.indexOf('@');
         const agentToken = (atIndex === -1 ? target : target.slice(0, atIndex)).trim();
@@ -1950,7 +2295,7 @@ export function resolveAgentVersionTargets(value, availableAgents, options = {})
             continue;
         }
         if (atIndex !== -1 && !versionToken) {
-            throw new Error(`Missing version in --agents entry '${target}'. Use agent@x.y.z or agent@default.`);
+            throw new Error(`Missing version in --agents entry '${target}'. Use agent@x.y.z, agent@default, or agent@all.`);
         }
         const agentId = resolveAgentName(agentToken);
         if (!agentId || !availableAgents.includes(agentId)) {
@@ -1990,8 +2335,13 @@ export function resolveAgentVersionTargets(value, availableAgents, options = {})
             explicitSelections.add(agentId);
             continue;
         }
+        if (versionToken === 'all') {
+            versionSelections.set(agentId, [...installedVersions]);
+            explicitSelections.add(agentId);
+            continue;
+        }
         if (!installedVersions.includes(versionToken)) {
-            throw new Error(`Version ${versionToken} is not installed for ${AGENTS[agentId].name}. Installed versions: ${installedVersions.join(', ')}`);
+            throw new VersionNotInstalledError(agentId, versionToken, installedVersions);
         }
         const explicitVersions = explicitSelections.has(agentId)
             ? (versionSelections.get(agentId) || [])
@@ -2014,10 +2364,28 @@ export function resolveInstalledAgentTargets(value, availableAgents, options = {
     const selectedAgents = [];
     const directAgents = [];
     const versionSelections = new Map();
-    const targets = value
+    const rawTargets = value
         .split(',')
         .map((item) => item.trim())
         .filter(Boolean);
+    // Expand literal `all` (with optional @all) into every available agent's all
+    // installed versions. Skip agents with no installed versions so `all` is
+    // lenient — only explicit `claude@all` errors when claude isn't installed.
+    // Mirrors resolveAgentVersionTargets so every --agents flag site supports
+    // the same selector syntax.
+    const targets = [];
+    for (const t of rawTargets) {
+        if (t === 'all' || t === 'all@all') {
+            for (const a of availableAgents) {
+                if (listInstalledVersions(a).length > 0) {
+                    targets.push(`${a}@all`);
+                }
+            }
+        }
+        else {
+            targets.push(t);
+        }
+    }
     const addVersionTarget = (agentId, version) => {
         const versions = versionSelections.get(agentId) || [];
         if (!versions.includes(version)) {
@@ -2037,7 +2405,7 @@ export function resolveInstalledAgentTargets(value, availableAgents, options = {
             continue;
         }
         if (atIndex !== -1 && !versionToken) {
-            throw new Error(`Missing version in --agents entry '${target}'. Use agent@x.y.z or agent@default.`);
+            throw new Error(`Missing version in --agents entry '${target}'. Use agent@x.y.z, agent@default, or agent@all.`);
         }
         const agentId = resolveAgentName(agentToken);
         if (!agentId || !availableAgents.includes(agentId)) {
@@ -2070,11 +2438,20 @@ export function resolveInstalledAgentTargets(value, availableAgents, options = {
             addVersionTarget(agentId, defaultVersion);
             continue;
         }
+        if (versionToken === 'all') {
+            if (installedVersions.length === 0) {
+                throw new Error(`No managed versions are installed for ${AGENTS[agentId].name}. Run: agents add ${agentId}@latest`);
+            }
+            for (const version of installedVersions) {
+                addVersionTarget(agentId, version);
+            }
+            continue;
+        }
         if (installedVersions.length === 0) {
             throw new Error(`No managed versions are installed for ${AGENTS[agentId].name}. Run: agents add ${agentId}@latest`);
         }
         if (!installedVersions.includes(versionToken)) {
-            throw new Error(`Version ${versionToken} is not installed for ${AGENTS[agentId].name}. Installed versions: ${installedVersions.join(', ')}`);
+            throw new VersionNotInstalledError(agentId, versionToken, installedVersions);
         }
         addVersionTarget(agentId, versionToken);
     }
@@ -2128,9 +2505,15 @@ export async function promptAgentVersionSelection(availableAgents, options = {})
         const defaultVer = getGlobalDefault(agentId);
         if (versions.length === 0)
             return `${AGENTS[agentId].name}  ${chalk.gray('(not installed)')}`;
-        if (defaultVer)
-            return `${AGENTS[agentId].name}  ${chalk.gray(`(active: ${defaultVer})`)}`;
-        return `${AGENTS[agentId].name}  ${chalk.gray(`(${versions[0]})`)}`;
+        // Surface the version count when there's more than one — mirrors the new
+        // `--agents <agent>@all` syntax so users can see at a glance how many
+        // versions `@all` would target before the per-version prompt fires.
+        const detail = versions.length > 1
+            ? (defaultVer
+                ? `active: ${defaultVer}, ${versions.length} versions installed`
+                : `${versions.length} versions installed`)
+            : (defaultVer ?? versions[0]);
+        return `${AGENTS[agentId].name}  ${chalk.gray(`(${detail})`)}`;
     };
     let selectedAgents;
     if (options.skipPrompts) {
@@ -2145,6 +2528,18 @@ export async function promptAgentVersionSelection(availableAgents, options = {})
         }
     }
     else {
+        // Non-TTY without an explicit --agents value used to silently fall through
+        // to default-picking inside the caller. That's surprising in scripts — fail
+        // loud and point at the new `--agents` syntax instead.
+        if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+            throw new Error('Non-interactive shell: cannot prompt for agent/version selection.\n' +
+                'Pass --agents explicitly. Examples:\n' +
+                '  --agents claude              (default version)\n' +
+                '  --agents claude@all          (every installed Claude version)\n' +
+                '  --agents claude@2.1.141      (a specific version)\n' +
+                '  --agents all                 (every installed version of every capable agent)\n' +
+                'Or pass --yes to auto-pick defaults.');
+        }
         // Prompt for agent selection
         const checkboxResult = await checkbox({
             message: 'Which agents should receive these resources?',
@@ -2179,7 +2574,7 @@ export async function promptAgentVersionSelection(availableAgents, options = {})
             const versionResult = await checkbox({
                 message: `Which versions of ${AGENTS[agentId].name} should receive these resources?`,
                 choices: [
-                    { name: chalk.bold('All versions'), value: 'all', checked: false },
+                    { name: chalk.bold(`All versions (${versions.length})`), value: 'all', checked: false },
                     ...versions.map((v) => {
                         const base = v === defaultVer ? `${v} (default)` : v;
                         let label = base.padEnd(maxLabelLen);