@phnx-labs/agents-cli 1.19.1 → 1.20.0

package/dist/lib/teams/worktree.js

@@ -8,7 +8,9 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as fs from 'fs/promises';
 import * as path from 'path';
+import { safeJoin } from '../paths.js';
 const execFileAsync = promisify(execFile);
+const WORKTREE_NAME_RE = /^[A-Za-z0-9_-]+$/;
 export async function isGitRepo(dir) {
     try {
         await execFileAsync('git', ['rev-parse', '--git-dir'], { cwd: dir });
@@ -42,8 +44,11 @@ export async function hasUncommittedChanges(worktreePath) {
  * @returns The absolute path to the created worktree
  */
 export async function createWorktree(repoDir, worktreeName) {
+    if (!WORKTREE_NAME_RE.test(worktreeName)) {
+        throw new Error(`Invalid worktree name: ${worktreeName}`);
+    }
     const gitRoot = await getGitRoot(repoDir);
-    const worktreePath = path.join(gitRoot, '.agents', 'worktrees', worktreeName);
+    const worktreePath = safeJoin(path.join(gitRoot, '.agents', 'worktrees'), worktreeName);
     const branchName = `agents/${worktreeName}`;
     await fs.mkdir(path.dirname(worktreePath), { recursive: true });
     await execFileAsync('git', ['worktree', 'add', '-b', branchName, worktreePath, 'HEAD'], {
@@ -59,8 +64,11 @@ export async function createWorktree(repoDir, worktreeName) {
  * @param deleteBranch - Whether to delete the associated branch
  */
 export async function removeWorktree(repoDir, worktreeName, deleteBranch = true) {
+    if (!WORKTREE_NAME_RE.test(worktreeName)) {
+        throw new Error(`Invalid worktree name: ${worktreeName}`);
+    }
     const gitRoot = await getGitRoot(repoDir);
-    const worktreePath = path.join(gitRoot, '.agents', 'worktrees', worktreeName);
+    const worktreePath = safeJoin(path.join(gitRoot, '.agents', 'worktrees'), worktreeName);
     const branchName = `agents/${worktreeName}`;
     try {
         await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], { cwd: gitRoot });
@@ -86,7 +94,10 @@ export async function removeWorktree(repoDir, worktreeName, deleteBranch = true)
  * Get the worktree path for a given name.
  */
 export function getWorktreePath(gitRoot, worktreeName) {
-    return path.join(gitRoot, '.agents', 'worktrees', worktreeName);
+    if (!WORKTREE_NAME_RE.test(worktreeName)) {
+        throw new Error(`Invalid worktree name: ${worktreeName}`);
+    }
+    return safeJoin(path.join(gitRoot, '.agents', 'worktrees'), worktreeName);
 }
 /**
  * Get the branch name for a worktree.

package/dist/lib/types.d.ts

@@ -6,7 +6,7 @@
  * formats for each supported agent.
  */
 /** Unique identifier for a supported AI coding agent. */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
 /** Preview features that users can opt into via `agents beta`. */
@@ -203,9 +203,12 @@ export interface RegistryConfig {
 /** Built-in registry endpoints shipped with agents-cli. */
 export declare const DEFAULT_REGISTRIES: Record<RegistryType, Record<string, RegistryConfig>>;
 /**
- * Registries that ship pre-seeded into new users' agents.yaml once, but are
- * not "defaults" — after seeding they behave like any user-added registry
- * (listable, disable-able, removable, and gone for good once removed).
+ * Third-party registries pre-seeded on first install for discoverability.
+ *
+ * These ship into new users' agents.yaml once, but are not "defaults" — after
+ * seeding they behave like any user-added registry (listable, disable-able,
+ * removable). Removed users can `agents registry remove <name>` to opt out;
+ * once removed they don't come back.
  */
 export declare const SEEDED_REGISTRIES: Record<RegistryType, Record<string, RegistryConfig>>;
 /** A single installable package within an MCP server entry. */

package/dist/lib/types.js

@@ -22,9 +22,12 @@ export const DEFAULT_REGISTRIES = {
     skill: {},
 };
 /**
- * Registries that ship pre-seeded into new users' agents.yaml once, but are
- * not "defaults" — after seeding they behave like any user-added registry
- * (listable, disable-able, removable, and gone for good once removed).
+ * Third-party registries pre-seeded on first install for discoverability.
+ *
+ * These ship into new users' agents.yaml once, but are not "defaults" — after
+ * seeding they behave like any user-added registry (listable, disable-able,
+ * removable). Removed users can `agents registry remove <name>` to opt out;
+ * once removed they don't come back.
  */
 export const SEEDED_REGISTRIES = {
     mcp: {},

package/dist/lib/versions.d.ts

@@ -63,7 +63,7 @@ export declare function hasNewResources(diff: AvailableResources, agent?: AgentI
  * Prompt user to select which NEW resources to sync.
  * Only shows resources that haven't been synced yet.
  */
-export declare function promptNewResourceSelection(agent: AgentId, newResources: AvailableResources): Promise<ResourceSelection | null>;
+export declare function promptNewResourceSelection(agent: AgentId, newResources: AvailableResources, version?: string): Promise<ResourceSelection | null>;
 /**
  * Prompt user to select which resources to sync from ~/.agents/.
  * Returns the selection, or null if user cancels.
@@ -118,7 +118,7 @@ export declare function listInstalledVersions(agent: AgentId): string[];
  * 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.
  */
@@ -163,6 +163,14 @@ export declare function softDeleteVersionDir(agent: AgentId, version: string): s
  * Nothing is hard-deleted.
  */
 export declare function removeVersion(agent: AgentId, version: string): boolean;
+/**
+ * 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 declare function printTrashFooter(moved: Array<{
+    agent: AgentId;
+    version: string;
+}>): void;
 /**
  * Remove all versions of an agent. Preserves each version's `home/` directory
  * so conversation history is never deleted; the per-version folders (now

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');
@@ -554,10 +562,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 +579,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 +603,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 +635,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 +656,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 +680,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 +892,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 +977,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.
  */
@@ -991,7 +1028,35 @@ 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' };
+        // Support agents that provide an installScript (cursor, roo, goose, kiro, grok, etc.)
+        if (agentConfig.installScript) {
+            // For grok we give special love because the user asked for first-class support
+            if (agent === 'grok') {
+                onProgress?.(`Installing Grok ${version} via official installer...`);
+                try {
+                    const script = agentConfig.installScript.replace('VERSION', version);
+                    // The official installer supports -s <version>
+                    const { exec } = await import('child_process');
+                    const { promisify } = await import('util');
+                    const execAsync = promisify(exec);
+                    await execAsync(script, { timeout: 120000 });
+                    onProgress?.('Grok binary installed. Setting up agents-cli version home for isolation...');
+                }
+                catch (err) {
+                    return { success: false, installedVersion: version, error: `Grok installer failed: ${err.message}` };
+                }
+            }
+            else {
+                return {
+                    success: false,
+                    installedVersion: version,
+                    error: `${agent} uses an external installer. Run: ${agentConfig.installScript}`,
+                };
+            }
+        }
+        else {
+            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
@@ -1004,7 +1069,15 @@ export async function installVersion(agent, version, onProgress) {
     // Create version directory and isolated home
     fs.mkdirSync(versionDir, { recursive: true });
     fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
-    // Initialize package.json
+    // For agents using external installers (especially grok), we don't do npm install.
+    // The binary is managed by the agent's own installer; we only manage the isolated home + resources.
+    if (agent === 'grok' || !agentConfig.npmPackage) {
+        // Grok (and similar) — binary already installed by the step above (or user ran external installer).
+        // We still want to record the version for config isolation.
+        createVersionedAlias(agent, version);
+        return { success: true, installedVersion: version };
+    }
+    // Initialize package.json (only for real npm agents)
     const packageJson = {
         name: `agents-${agent}-${version}`,
         version: '1.0.0',
@@ -1147,8 +1220,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 +1246,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
@@ -1626,13 +1714,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 +1753,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 fixed by RUSH-670 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 +1801,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 +1823,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 +1890,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 +1931,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 +1979,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 +2033,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)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.19.1",
-  "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
+  "version": "1.20.0",
+  "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
@@ -23,8 +23,7 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
-    "dist/lib/secrets/AgentsKeychain.app/**",
-    "npm-shrinkwrap.json",
+    "dist/lib/secrets/Agents CLI.app/**",
     "scripts/postinstall.js",
     "CHANGELOG.md",
     "README.md",
@@ -42,7 +41,7 @@
     "url": "https://github.com/phnx-labs/agents-cli/issues"
   },
   "scripts": {
-    "build": "tsc && rm -rf dist/lib/secrets/AgentsKeychain.app && ([ \"$(uname)\" = \"Darwin\" ] && cp -R bin/AgentsKeychain.app dist/lib/secrets/AgentsKeychain.app || true)",
+    "build": "tsc && rm -rf 'dist/lib/secrets/AgentsKeychain.app' 'dist/lib/secrets/Agents CLI.app' && ([ \"$(uname)\" = \"Darwin\" ] && cp -R 'bin/Agents CLI.app' 'dist/lib/secrets/Agents CLI.app' || true)",
     "prepack": "scripts/verify-keychain-helper.sh",
     "postinstall": "node scripts/postinstall.js",
     "dev": "tsx src/index.ts",
@@ -59,6 +58,8 @@
     "gemini",
     "cursor",
     "opencode",
+    "grok",
+    "xai",
     "mcp",
     "skills",
     "ai",
@@ -72,14 +73,14 @@
     "npm": ">=9"
   },
   "dependencies": {
-    "@inquirer/prompts": "7.10.1",
+    "@inquirer/prompts": "8.5.1",
     "@types/proper-lockfile": "4.1.4",
     "@xterm/headless": "6.0.0",
     "@zed-industries/agent-client-protocol": "0.4.5",
     "chalk": "5.6.2",
     "commander": "12.1.0",
     "croner": "9.1.0",
-    "diff": "8.0.4",
+    "diff": "9.0.0",
     "marked": "15.0.12",
     "marked-terminal": "7.3.0",
     "node-pty": "1.1.0",
@@ -93,8 +94,7 @@
     "@types/diff": "6.0.0",
     "@types/marked-terminal": "6.1.1",
     "@types/node": "22.19.10",
-    "playwright": "1.59.1",
-    "tsx": "4.22.2",
+    "tsx": "4.22.3",
     "typescript": "5.9.3",
     "vitest": "4.1.6"
   }