@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/versions.js

@@ -1,23 +1,53 @@
+/**
+ * Version management module for agents-cli.
+ *
+ * Handles installing, removing, listing, and switching between agent CLI versions.
+ * Each version is installed into an isolated directory under ~/.agents-system/versions/{agent}/{version}/
+ * with its own HOME directory for config isolation. Resources (commands, skills, hooks, memory,
+ * MCP servers, permissions, subagents, plugins) from ~/.agents/ are synced into version homes
+ * via copies or conversions (not symlinks).
+ *
+ * Key responsibilities:
+ * - Version lifecycle: install, remove, list, resolve (project-level or global default)
+ * - Resource discovery: scan ~/.agents/ for available resources across all types
+ * - Resource sync: copy/convert resources into a version's isolated config directory
+ * - Diff and reconciliation: detect new/unsynced resources and prompt users to sync them
+ * - Agent/version target resolution: parse agent@version specs from CLI flags
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { exec } from 'child_process';
+import * as yaml from 'yaml';
+import { exec, execFile } from 'child_process';
 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, getMemoryDir, clearVersionResources, recordVersionResources, getProjectAgentsDir } from './state.js';
-import { AGENTS, getAccountEmail, MCP_CAPABLE_AGENTS, COMMANDS_CAPABLE_AGENTS, getMcpConfigPathForHome, parseMcpConfig, resolveAgentName, formatAgentError, CODEX_HOOKS_MIN_VERSION } from './agents.js';
-import { applyPermissionsToVersion as applyPermsToVersion, PERMISSIONS_CAPABLE_AGENTS, discoverPermissionGroups, buildPermissionsFromGroups, CODEX_RULES_FILENAME } from './permissions.js';
+import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, clearVersionResources, recordVersionResources, getProjectAgentsDir, getPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir } from './state.js';
+import { resolveResource } 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, getActivePermissionSetName, readPermissionSetRecipe, PERMISSION_SET_ENV_VAR } from './permissions.js';
 import { installMcpServers } from './mcp.js';
 import { markdownToToml } from './convert.js';
-import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion } from './shims.js';
+import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
 import { listInstalledSubagents, transformSubagentForClaude, syncSubagentToOpenclaw, SUBAGENT_CAPABLE_AGENTS } from './subagents.js';
 import { registerHooksToSettings } from './hooks.js';
+import { supports, explainSkip } from './capabilities.js';
 import { discoverPlugins, syncPluginToVersion, isPluginSynced, pluginSupportsAgent, cleanOrphanedPluginSkills } from './plugins.js';
 import { compileMemoryForAgent } from './memory-compile.js';
+import { loadSyncManifest, saveSyncManifest, buildManifest, isSyncStale } from './sync-manifest.js';
 import { PLUGINS_CAPABLE_AGENTS } from './agents.js';
+import { safeJoin } from './paths.js';
+import { installCommandSkillToVersion, listCommandSkillsInVersion, shouldInstallCommandAsSkill } from './command-skills.js';
+/** Promisified exec for running shell commands. */
 const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+const RULES_DOC_FILENAME = 'README.md';
+// Strict shape for an agent version string. Anything outside this is rejected
+// at parse time so it can't reach an exec/shell boundary or get interpolated
+// into a generated bash alias. Must allow "latest" plus npm-dist-tag /
+// semver-shaped values (digits, dots, dashes, +, _).
+const VERSION_RE = /^(?:latest|[A-Za-z0-9._+-]{1,64})$/;
 /**
  * Get all available resources from ~/.agents/.
  */
@@ -31,14 +61,22 @@ export function getAvailableResources(cwd = process.cwd()) {
         permissions: [],
         subagents: [],
         plugins: [],
+        promptcuts: false,
     };
     const projectAgentsDir = getProjectAgentsDir(cwd);
-    const userBase = path.dirname(getCommandsDir());
+    const userBase = getUserAgentsDir();
+    const systemBase = getAgentsDir();
     const resourceBases = [];
     if (projectAgentsDir) {
         resourceBases.push({ scope: 'project', base: projectAgentsDir });
     }
     resourceBases.push({ scope: 'user', base: userBase });
+    resourceBases.push({ scope: 'user', base: systemBase });
+    // Extra DotAgent repos registered via `agents repo add`. Ordered last so
+    // project/user/system names win on collision.
+    for (const extra of getEnabledExtraRepos()) {
+        resourceBases.push({ scope: 'user', base: extra.dir });
+    }
     // Commands (*.md files)
     const commandNames = new Set();
     for (const { base } of resourceBases) {
@@ -79,22 +117,25 @@ export function getAvailableResources(cwd = process.cwd()) {
         }
     }
     result.hooks = Array.from(hookNames);
-    // Memory (*.md files, excluding symlinks)
+    // Rules (*.md files, excluding symlinks and README)
+    // Scan 'rules/' first (canonical), then 'memory/' (legacy name) for backward compat.
     const memoryNames = new Set();
     for (const { base } of resourceBases) {
-        const memoryDir = path.join(base, 'memory');
-        if (!fs.existsSync(memoryDir))
-            continue;
-        const names = fs.readdirSync(memoryDir)
-            .filter(f => {
-            if (!f.endsWith('.md'))
-                return false;
-            const stat = fs.lstatSync(path.join(memoryDir, f));
-            return !stat.isSymbolicLink();
-        })
-            .map(f => f.replace(/\.md$/, ''));
-        for (const name of names) {
-            memoryNames.add(name);
+        for (const subdir of ['rules', 'memory']) {
+            const memoryDir = path.join(base, subdir);
+            if (!fs.existsSync(memoryDir))
+                continue;
+            const names = fs.readdirSync(memoryDir)
+                .filter(f => {
+                if (!f.endsWith('.md') || f === RULES_DOC_FILENAME)
+                    return false;
+                const stat = fs.lstatSync(path.join(memoryDir, f));
+                return !stat.isSymbolicLink();
+            })
+                .map(f => f.replace(/\.md$/, ''));
+            for (const name of names) {
+                memoryNames.add(name);
+            }
         }
     }
     result.memory = Array.from(memoryNames);
@@ -143,14 +184,28 @@ export function getAvailableResources(cwd = process.cwd()) {
     // Plugins (directories with .claude-plugin/plugin.json)
     const allPlugins = discoverPlugins();
     result.plugins = allPlugins.map(p => p.name);
+    // Promptcuts — single file at ~/.agents/promptcuts.yaml, not per-agent.
+    // Project-scoped .agents/promptcuts.yaml is intentionally not supported
+    // (user-global shortcuts only — they follow the user, not the repo).
+    result.promptcuts = fs.existsSync(getPromptcutsPath());
     return result;
 }
+// Files/dirs that are never synced into a version home (OS metadata, local tooling).
+const SKILL_COPY_IGNORE = new Set(['.DS_Store', '.git', '.gitignore', '.venv', '__pycache__', 'node_modules']);
+function shouldSkillEntryBeSkipped(name) {
+    return SKILL_COPY_IGNORE.has(name);
+}
 /**
  * Recursively compare two directories: every file in src must exist in dest with identical content.
+ * Skips the same entries that copyDir skips (symlinks and SKILL_COPY_IGNORE members).
  */
 function skillDirsMatch(src, dest) {
     const entries = fs.readdirSync(src, { withFileTypes: true });
     for (const entry of entries) {
+        if (entry.isSymbolicLink())
+            continue;
+        if (shouldSkillEntryBeSkipped(entry.name))
+            continue;
         const srcPath = path.join(src, entry.name);
         const destPath = path.join(dest, entry.name);
         if (entry.isDirectory()) {
@@ -188,6 +243,7 @@ export function getActuallySyncedResources(agent, version, options = {}) {
         permissions: [],
         subagents: [],
         plugins: [],
+        promptcuts: false,
     };
     // Commands - check what files exist in version home
     const commandsDir = path.join(configDir, agentConfig.commandsSubdir);
@@ -201,21 +257,27 @@ export function getActuallySyncedResources(agent, version, options = {}) {
     const skillsDir = path.join(configDir, 'skills');
     const centralSkillsDir = getSkillsDir();
     const projectSkillsDir = projectAgentsDir ? path.join(projectAgentsDir, 'skills') : null;
+    const userAgentsDir = getUserAgentsDir();
+    const extraRepos = getEnabledExtraRepos();
     if (fs.existsSync(skillsDir)) {
         const installedSkills = fs.readdirSync(skillsDir, { withFileTypes: true })
             .filter(d => d.isDirectory() && !d.name.startsWith('.'))
             .map(d => d.name);
         for (const skill of installedSkills) {
             const versionSkillDir = path.join(skillsDir, skill);
-            const projectSourceDir = projectSkillsDir ? path.join(projectSkillsDir, skill) : null;
-            const centralSkillDir = path.join(centralSkillsDir, skill);
-            const hasProjectSource = projectSourceDir ? fs.existsSync(projectSourceDir) : false;
-            const hasUserSource = fs.existsSync(centralSkillDir);
-            if (!hasProjectSource && !hasUserSource) {
+            const sourceCandidates = [
+                projectSkillsDir ? path.join(projectSkillsDir, skill) : null,
+                path.join(userAgentsDir, 'skills', skill),
+                path.join(centralSkillsDir, skill),
+                ...extraRepos.map((e) => path.join(e.dir, 'skills', skill)),
+            ];
+            const sourceDir = sourceCandidates.find((p) => p && fs.existsSync(p)) || null;
+            if (!sourceDir) {
+                // True orphan — no source in project, primary, or any extra. Still
+                // count as synced so version-home cleanup knows it's accounted for.
                 result.skills.push(skill);
                 continue;
             }
-            const sourceDir = hasProjectSource ? projectSourceDir : centralSkillDir;
             const allMatch = skillDirsMatch(sourceDir, versionSkillDir);
             if (allMatch) {
                 result.skills.push(skill);
@@ -226,16 +288,19 @@ export function getActuallySyncedResources(agent, version, options = {}) {
     const hooksDir = path.join(configDir, 'hooks');
     const centralHooksDir = getHooksDir();
     const projectHooksDir = projectAgentsDir ? path.join(projectAgentsDir, 'hooks') : null;
+    const userHooksDir = path.join(userAgentsDir, 'hooks');
     if (fs.existsSync(hooksDir)) {
         const installedHooks = fs.readdirSync(hooksDir).filter(f => !f.startsWith('.'));
         for (const hook of installedHooks) {
             const projectFile = projectHooksDir ? path.join(projectHooksDir, hook) : null;
             const centralFile = path.join(centralHooksDir, hook);
+            const userFile = path.join(userHooksDir, hook);
             const versionFile = path.join(hooksDir, hook);
             const hasProject = projectFile ? fs.existsSync(projectFile) : false;
+            const hasUser = fs.existsSync(userFile);
             const hasCentral = fs.existsSync(centralFile);
-            const sourceFile = hasProject ? projectFile : centralFile;
-            if (!hasProject && !hasCentral) {
+            const sourceFile = hasProject ? projectFile : hasUser ? userFile : centralFile;
+            if (!hasProject && !hasCentral && !hasUser) {
                 result.hooks.push(hook);
                 continue;
             }
@@ -251,15 +316,19 @@ export function getActuallySyncedResources(agent, version, options = {}) {
             }
         }
     }
-    // Memory - check which memory files are actually in sync (content matches)
-    const memoryDir = getMemoryDir();
-    const projectMemoryDir = projectAgentsDir ? path.join(projectAgentsDir, 'memory') : null;
+    // Rules - check which instruction files are actually in sync (content matches)
+    const memoryDir = getResolvedRulesDir();
+    const projectMemoryDir = projectAgentsDir ? path.join(projectAgentsDir, 'rules') : null;
+    const userMemoryDir = getUserRulesDir();
     const memoryFiles = new Set();
     if (fs.existsSync(memoryDir)) {
-        fs.readdirSync(memoryDir).filter(f => f.endsWith('.md')).forEach(f => memoryFiles.add(f));
+        fs.readdirSync(memoryDir).filter(f => f.endsWith('.md') && f !== RULES_DOC_FILENAME).forEach(f => memoryFiles.add(f));
     }
     if (projectMemoryDir && fs.existsSync(projectMemoryDir)) {
-        fs.readdirSync(projectMemoryDir).filter(f => f.endsWith('.md')).forEach(f => memoryFiles.add(f));
+        fs.readdirSync(projectMemoryDir).filter(f => f.endsWith('.md') && f !== RULES_DOC_FILENAME).forEach(f => memoryFiles.add(f));
+    }
+    if (fs.existsSync(userMemoryDir)) {
+        fs.readdirSync(userMemoryDir).filter(f => f.endsWith('.md') && f !== RULES_DOC_FILENAME).forEach(f => memoryFiles.add(f));
     }
     for (const file of memoryFiles) {
         const memName = file.replace(/\.md$/, '');
@@ -269,10 +338,12 @@ export function getActuallySyncedResources(agent, version, options = {}) {
             continue;
         const projectFile = projectMemoryDir ? path.join(projectMemoryDir, file) : null;
         const centralFile = path.join(memoryDir, file);
+        const userFile = path.join(userMemoryDir, file);
         const hasProject = projectFile ? fs.existsSync(projectFile) : false;
+        const hasUser = fs.existsSync(userFile);
         const hasCentral = fs.existsSync(centralFile);
-        const sourceFile = hasProject ? projectFile : centralFile;
-        if (!hasProject && !hasCentral) {
+        const sourceFile = hasProject ? projectFile : hasUser ? userFile : centralFile;
+        if (!hasProject && !hasCentral && !hasUser) {
             result.memory.push(memName);
             continue;
         }
@@ -421,6 +492,9 @@ export function getNewResources(available, actuallySynced) {
         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)),
+        // 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,
     };
 }
 /**
@@ -643,8 +717,9 @@ export async function promptResourceSelection(agent) {
     if (selectedCategories.length === 0) {
         return {};
     }
-    // If "Select All" was picked, sync everything without per-category prompts
-    if (selectedCategories.includes(SELECT_ALL_KEY)) {
+    // If "Select All" was picked, or all individual categories are selected, sync everything without per-category prompts
+    const allCategoryKeys = availableCategories.map(c => c.key);
+    if (selectedCategories.includes(SELECT_ALL_KEY) || allCategoryKeys.every(k => selectedCategories.includes(k))) {
         for (const c of availableCategories) {
             selection[c.key] = 'all';
         }
@@ -728,6 +803,11 @@ export function parseAgentSpec(spec) {
     if (!AGENTS[agentName]) {
         return null;
     }
+    // Reject any version string that could escape an exec context or a
+    // bash-shim interpolation. Real agent versions are semver-shaped or "latest".
+    if (!VERSION_RE.test(version)) {
+        return null;
+    }
     return {
         agent: agentName,
         version,
@@ -769,7 +849,7 @@ export async function getLatestNpmVersion(agent) {
     if (!agentConfig.npmPackage)
         return null;
     try {
-        const { stdout } = await execAsync(`npm view ${agentConfig.npmPackage} version`);
+        const { stdout } = await execFileAsync('npm', ['view', agentConfig.npmPackage, 'version']);
         return stdout.trim();
     }
     catch {
@@ -853,9 +933,15 @@ export async function installVersion(agent, version, onProgress) {
     const packageSpec = version === 'latest'
         ? agentConfig.npmPackage
         : `${agentConfig.npmPackage}@${version}`;
+    // Defense-in-depth: even if a future caller bypasses parseAgentSpec, the
+    // version string never reaches /bin/sh because we use execFile (argv form)
+    // and re-validate here.
+    if (version !== 'latest' && !VERSION_RE.test(version)) {
+        throw new Error(`Invalid version: ${JSON.stringify(version)}`);
+    }
     try {
         onProgress?.(`Installing ${packageSpec}...`);
-        const { stdout } = await execAsync(`npm install ${packageSpec}`, { cwd: versionDir });
+        const { stdout } = await execFileAsync('npm', ['install', packageSpec], { cwd: versionDir });
         // Determine the actual installed version
         let installedVersion = version;
         if (version === 'latest') {
@@ -873,8 +959,10 @@ export async function installVersion(agent, version, onProgress) {
                             fs.renameSync(versionDir, actualVersionDir);
                         }
                         else {
-                            // Already exists, remove the 'latest' dir
-                            fs.rmSync(versionDir, { recursive: true, force: true });
+                            // Already exists — drop the 'latest' install artifacts but keep
+                            // `home/` (may contain conversation history from sessions that
+                            // ran while the user was on `latest`).
+                            removeInstallArtifacts(versionDir);
                         }
                     }
                 }
@@ -886,25 +974,52 @@ export async function installVersion(agent, version, onProgress) {
         }
         // Create versioned alias (e.g., claude@2.0.65)
         createVersionedAlias(agent, installedVersion);
+        // Claude reads its global config from CLAUDE_CONFIG_DIR/.claude.json —
+        // i.e. inside the per-version .claude dir — while the rest of agents-cli
+        // manages the home-level file. Symlink INSIDE to OUTSIDE so Claude and
+        // agents-cli see the same content.
+        if (agent === 'claude') {
+            try {
+                ensureClaudeInsideSymlink(installedVersion);
+            }
+            catch {
+                /* non-fatal; the install itself succeeded */
+            }
+        }
         return { success: true, installedVersion };
     }
     catch (err) {
-        // Clean up on failure
+        // Clean up on failure — preserve `home/` in case a prior install left
+        // conversation history behind that we must not wipe on a failed reinstall.
         if (fs.existsSync(versionDir)) {
-            fs.rmSync(versionDir, { recursive: true, force: true });
+            removeInstallArtifacts(versionDir);
         }
         return { success: false, installedVersion: version, error: err.message };
     }
 }
 /**
- * Remove a specific version of an agent.
+ * Remove install artifacts from a version directory, preserving `home/` which
+ * contains the user's conversation history, sessions, history.jsonl, tasks,
+ * todos, file-history, etc. Called by removeVersion so that uninstalling a
+ * version never deletes the user's transcripts.
+ */
+function removeInstallArtifacts(versionDir) {
+    for (const entry of fs.readdirSync(versionDir)) {
+        if (entry === 'home')
+            continue;
+        fs.rmSync(path.join(versionDir, entry), { recursive: true, force: true });
+    }
+}
+/**
+ * Remove a specific version of an agent. Preserves `home/` under the version
+ * directory so conversation history survives reinstalls.
  */
 export function removeVersion(agent, version) {
     const versionDir = getVersionDir(agent, version);
     if (!fs.existsSync(versionDir)) {
         return false;
     }
-    fs.rmSync(versionDir, { recursive: true, force: true });
+    removeInstallArtifacts(versionDir);
     // Remove versioned alias (e.g., claude@2.0.65)
     removeVersionedAlias(agent, version);
     // Clear resource tracking for this version
@@ -935,7 +1050,9 @@ export function removeVersion(agent, version) {
     return true;
 }
 /**
- * Remove all versions of an agent.
+ * Remove all versions of an agent. Preserves each version's `home/` directory
+ * so conversation history is never deleted; the per-version folders (now
+ * containing only `home/`) remain under the agent dir.
  */
 export function removeAllVersions(agent) {
     const versions = listInstalledVersions(agent);
@@ -945,11 +1062,6 @@ export function removeAllVersions(agent) {
             removed++;
         }
     }
-    // Clean up the agent directory
-    const agentDir = path.join(getVersionsDir(), agent);
-    if (fs.existsSync(agentDir)) {
-        fs.rmSync(agentDir, { recursive: true, force: true });
-    }
     return removed;
 }
 /**
@@ -968,19 +1080,71 @@ export function resolveVersion(agent, projectPath) {
     return getGlobalDefault(agent);
 }
 /**
- * Get version specified in project manifest.
+ * Normalize a user-supplied @version token across CLI subcommands.
+ *
+ *   undefined / "" / "default"  -> undefined  (caller falls back to project pin or global default)
+ *   "latest"                    -> highest installed version (process.exit if none installed)
+ *   "x.y.z" (installed)         -> "x.y.z"
+ *   "x.y.z" (not installed)     -> process.exit with installed-list hint
+ *
+ * Use this anywhere the user can type `agents <cmd> claude@<token>` to keep the
+ * vocabulary consistent. Subcommands with different semantics for `latest`
+ * (install/remove/use, where `latest` means npm-latest) keep their existing
+ * parsing.
+ */
+export function resolveVersionAlias(agent, raw) {
+    if (!raw || raw === 'default')
+        return undefined;
+    if (raw === 'latest') {
+        const installed = listInstalledVersions(agent);
+        if (installed.length === 0) {
+            console.error(chalk.red(`No ${agent} versions installed.`));
+            console.error(chalk.gray(`Install one: agents versions install ${agent}`));
+            process.exit(1);
+        }
+        return installed[installed.length - 1];
+    }
+    if (!isVersionInstalled(agent, raw)) {
+        const installed = listInstalledVersions(agent);
+        console.error(chalk.red(`${agent}@${raw} is not installed.`));
+        if (installed.length > 0) {
+            console.error(chalk.gray(`Installed: ${installed.join(', ')}`));
+        }
+        console.error(chalk.gray(`Install it: agents versions install ${agent}@${raw}`));
+        process.exit(1);
+    }
+    return raw;
+}
+/**
+ * Loose variant of resolveVersionAlias for record-filter contexts (sessions,
+ * team history). Same `default`/`latest` semantics, but explicit versions
+ * pass through unchanged so historical records of uninstalled versions remain
+ * queryable.
+ */
+export function resolveVersionAliasLoose(agent, raw) {
+    if (!raw || raw === 'default')
+        return undefined;
+    if (raw === 'latest') {
+        const installed = listInstalledVersions(agent);
+        return installed.length > 0 ? installed[installed.length - 1] : undefined;
+    }
+    return raw;
+}
+/**
+ * Get version specified in a project-root agents.yaml (not the user ~/.agents-system/agents.yaml).
  */
 export function getProjectVersion(agent, startPath) {
+    const userAgentsYaml = path.join(getAgentsDir(), 'agents.yaml');
     let dir = path.resolve(startPath);
     while (dir !== path.dirname(dir)) {
-        const manifestPath = path.join(dir, '.agents', 'agents.yaml');
-        if (fs.existsSync(manifestPath)) {
+        const manifestPath = path.join(dir, 'agents.yaml');
+        if (manifestPath !== userAgentsYaml && fs.existsSync(manifestPath)) {
             try {
                 const content = fs.readFileSync(manifestPath, 'utf-8');
-                // Simple YAML parsing for agents section (flat format: claude: "1.5.0")
-                const agentMatch = content.match(new RegExp(`^\\s+${agent}:\\s*['"]?([^'"\n]+)['"]?`, 'm'));
-                if (agentMatch) {
-                    return agentMatch[1].trim();
+                const parsed = yaml.parse(content);
+                const version = parsed?.agents?.[agent];
+                if (typeof version === 'string' && version.trim()) {
+                    return version.trim();
                 }
             }
             catch {
@@ -1015,7 +1179,7 @@ export async function getInstalledVersion(agent, version) {
         return null;
     }
     try {
-        const { stdout } = await execAsync(`${binaryPath} --version`);
+        const { stdout } = await execFileAsync(binaryPath, ['--version']);
         const match = stdout.match(/(\d+\.\d+\.\d+)/);
         return match ? match[1] : version;
     }
@@ -1058,10 +1222,28 @@ export function getResourceDiff(agent, version) {
             return 'none';
         }
     };
-    // Commands: check directory symlink (or individual files for Gemini)
+    // Commands: check directory symlink (or individual files for Gemini / generated skills for newer Codex)
     const centralCommands = getCommandsDir();
     const commandsTarget = path.join(agentDir, agentConfig.commandsSubdir);
-    if (agentConfig.format === 'toml') {
+    if (shouldInstallCommandAsSkill(agent, version)) {
+        const centralFiles = fs.existsSync(centralCommands)
+            ? fs.readdirSync(centralCommands).filter(f => f.endsWith('.md'))
+            : [];
+        const centralNames = new Set(centralFiles.map(f => f.replace('.md', '')));
+        const versionNames = new Set(listCommandSkillsInVersion(agentDir));
+        for (const file of centralFiles) {
+            const name = file.replace('.md', '');
+            if (!versionNames.has(name)) {
+                diff.commands.added.push(file);
+            }
+        }
+        for (const name of versionNames) {
+            if (!centralNames.has(name)) {
+                diff.commands.dangling.push(`${name}.md`);
+            }
+        }
+    }
+    else if (agentConfig.format === 'toml') {
         // Gemini: compare .md files in central vs .toml files in version
         if (fs.existsSync(centralCommands)) {
             const centralFiles = fs.readdirSync(centralCommands).filter(f => f.endsWith('.md'));
@@ -1125,10 +1307,10 @@ export function getResourceDiff(agent, version) {
             diff.hooks.dangling = ['hooks/'];
         }
     }
-    // Memory: check individual file symlinks
-    const centralMemory = getMemoryDir();
+    // Rules: check individual file symlinks
+    const centralMemory = getResolvedRulesDir();
     if (fs.existsSync(centralMemory)) {
-        const memoryFiles = fs.readdirSync(centralMemory).filter(f => f.endsWith('.md'));
+        const memoryFiles = fs.readdirSync(centralMemory).filter(f => f.endsWith('.md') && f !== RULES_DOC_FILENAME);
         for (const file of memoryFiles) {
             const targetName = file === 'AGENTS.md' ? agentConfig.instructionsFile : file;
             const targetPath = path.join(agentDir, targetName);
@@ -1166,7 +1348,20 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     const result = { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [] };
     const cwd = options.cwd || process.cwd();
     const projectAgentsDir = options.projectDir || getProjectAgentsDir(cwd);
+    const userAgentsDir = getUserAgentsDir();
+    // Extra DotAgent repos registered via `agents repo add`. Looked up last so
+    // project/user/system repos win on name collisions.
+    const extraRepos = getEnabledExtraRepos();
     const available = getAvailableResources(cwd);
+    // 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 ~2ms (stat calls + manifest read).
+    if (!selection && !options.force) {
+        const manifest = loadSyncManifest(agent, version);
+        if (manifest && !isSyncStale(manifest, available, agent, version, cwd)) {
+            return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [] };
+        }
+    }
     // Helper: remove a path (symlink or real) if it exists
     const removePath = (p) => {
         try {
@@ -1185,12 +1380,16 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         fs.mkdirSync(dest, { recursive: true });
         const entries = fs.readdirSync(src, { withFileTypes: true });
         for (const entry of entries) {
-            const srcPath = path.join(src, entry.name);
-            const destPath = path.join(dest, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            if (shouldSkillEntryBeSkipped(entry.name))
+                continue;
+            const srcPath = safeJoin(src, entry.name);
+            const destPath = safeJoin(dest, entry.name);
             if (entry.isDirectory()) {
                 copyDir(srcPath, destPath);
             }
-            else {
+            else if (entry.isFile()) {
                 fs.copyFileSync(srcPath, destPath);
             }
         }
@@ -1199,8 +1398,10 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     const resolveSelection = (sel, available) => {
         if (sel === 'all')
             return available;
-        if (Array.isArray(sel))
-            return sel;
+        if (Array.isArray(sel)) {
+            const availableSet = new Set(available);
+            return sel.filter((item) => availableSet.has(item));
+        }
         return [];
     };
     // Sync commands
@@ -1208,24 +1409,38 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         ? resolveSelection(selection.commands, available.commands)
         : available.commands; // No selection = sync all
     if (commandsToSync.length > 0 && COMMANDS_CAPABLE_AGENTS.includes(agent)) {
-        const centralCommands = getCommandsDir();
-        const projectCommandsDir = projectAgentsDir ? path.join(projectAgentsDir, 'commands') : null;
         const commandsTarget = path.join(agentDir, agentConfig.commandsSubdir);
-        fs.mkdirSync(commandsTarget, { recursive: true });
+        const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
+        if (commandsAsSkills) {
+            removePath(commandsTarget);
+        }
+        else {
+            fs.mkdirSync(commandsTarget, { recursive: true });
+        }
         const syncedCommands = [];
         for (const cmd of commandsToSync) {
-            const projectSource = projectCommandsDir ? path.join(projectCommandsDir, `${cmd}.md`) : null;
-            const userSource = path.join(centralCommands, `${cmd}.md`);
-            const srcFile = projectSource && fs.existsSync(projectSource) ? projectSource : userSource;
-            if (!fs.existsSync(srcFile))
+            const resolved = resolveResource('commands', `${cmd}.md`, cwd);
+            if (!resolved || fs.lstatSync(resolved.path).isSymbolicLink())
                 continue;
-            if (agentConfig.format === 'toml') {
+            const srcFile = resolved.path;
+            if (commandsAsSkills) {
+                const skillSourceDirs = [
+                    projectAgentsDir ? path.join(projectAgentsDir, 'skills') : null,
+                    path.join(userAgentsDir, 'skills'),
+                    getSkillsDir(),
+                    ...extraRepos.map((e) => path.join(e.dir, 'skills')),
+                ];
+                const installed = installCommandSkillToVersion(agentDir, cmd, srcFile, skillSourceDirs);
+                if (!installed.success)
+                    continue;
+            }
+            else if (agentConfig.format === 'toml') {
                 const content = fs.readFileSync(srcFile, 'utf-8');
                 const tomlContent = markdownToToml(cmd, content);
-                fs.writeFileSync(path.join(commandsTarget, `${cmd}.toml`), tomlContent);
+                fs.writeFileSync(safeJoin(commandsTarget, `${cmd}.toml`), tomlContent);
             }
             else {
-                fs.copyFileSync(srcFile, path.join(commandsTarget, `${cmd}.md`));
+                fs.copyFileSync(srcFile, safeJoin(commandsTarget, `${cmd}.md`));
             }
             syncedCommands.push(cmd);
         }
@@ -1245,17 +1460,17 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             ? resolveSelection(selection.skills, available.skills)
             : available.skills;
         if (skillsToSync.length > 0) {
-            const centralSkills = getSkillsDir();
-            const projectSkills = projectAgentsDir ? path.join(projectAgentsDir, 'skills') : null;
             const skillsTarget = path.join(agentDir, 'skills');
             fs.mkdirSync(skillsTarget, { recursive: true });
             const syncedSkills = [];
             for (const skill of skillsToSync) {
-                const projectSource = projectSkills ? path.join(projectSkills, skill) : null;
-                const srcDir = projectSource && fs.existsSync(projectSource) ? projectSource : path.join(centralSkills, skill);
-                if (!fs.existsSync(srcDir))
+                const resolved = resolveResource('skills', skill, cwd);
+                const srcDir = resolved && fs.existsSync(resolved.path) && fs.lstatSync(resolved.path).isDirectory()
+                    ? resolved.path
+                    : null;
+                if (!srcDir)
                     continue;
-                const destDir = path.join(skillsTarget, skill);
+                const destDir = safeJoin(skillsTarget, skill);
                 removePath(destDir);
                 copyDir(srcDir, destDir);
                 syncedSkills.push(skill);
@@ -1266,11 +1481,11 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             }
         }
     }
-    // Sync hooks (if agent supports them)
+    // Sync hooks (if agent supports them at this version)
+    const hooksGate = supports(agent, 'hooks', version);
     if (agentConfig.supportsHooks) {
-        // Version gate: Codex hooks require >= CODEX_HOOKS_MIN_VERSION
-        if (agent === 'codex' && compareVersions(version, CODEX_HOOKS_MIN_VERSION) < 0) {
-            console.warn(`hooks skipped: codex@${version} < ${CODEX_HOOKS_MIN_VERSION}`);
+        if (!hooksGate.ok) {
+            console.warn(explainSkip(agent, 'hooks', hooksGate, version) + ' -- skipped');
         }
         else {
             const hooksToSync = selection
@@ -1278,25 +1493,63 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                 : available.hooks;
             if (hooksToSync.length > 0) {
                 const centralHooks = getHooksDir();
-                const projectHooksDir = projectAgentsDir ? path.join(projectAgentsDir, 'hooks') : null;
                 const hooksTarget = path.join(agentDir, 'hooks');
                 fs.mkdirSync(hooksTarget, { recursive: true });
                 const syncedHooks = [];
                 for (const hook of hooksToSync) {
-                    const projectSource = projectHooksDir ? path.join(projectHooksDir, hook) : null;
-                    const srcFile = projectSource && fs.existsSync(projectSource) ? projectSource : path.join(centralHooks, hook);
-                    if (!fs.existsSync(srcFile))
+                    // Hooks are executable shell scripts that run on agent events. We
+                    // intentionally do NOT pull from the project's own .agents/hooks/
+                    // directory: that would let any cloned public repo plant an
+                    // executable that fires the next time the user runs `agents use`
+                    // inside that repo. Hooks must come from the user's central
+                    // ~/.agents/hooks/ or an explicitly enabled extra repo.
+                    const candidates = [
+                        safeJoin(path.join(userAgentsDir, 'hooks'), hook),
+                        safeJoin(centralHooks, hook),
+                        ...extraRepos.map((e) => safeJoin(path.join(e.dir, 'hooks'), hook)),
+                    ];
+                    const srcFile = candidates.find((p) => p && fs.existsSync(p) && !fs.lstatSync(p).isSymbolicLink()) || null;
+                    if (!srcFile)
                         continue;
-                    const destFile = path.join(hooksTarget, hook);
+                    const destFile = safeJoin(hooksTarget, hook);
                     fs.copyFileSync(srcFile, destFile);
                     fs.chmodSync(destFile, 0o755);
                     syncedHooks.push(hook);
                 }
+                // Remove orphan hook files that exist in version home but not in any trusted source.
+                const centralHookNames = new Set(fs.existsSync(getHooksDir())
+                    ? fs.readdirSync(getHooksDir()).filter(f => !f.startsWith('.'))
+                    : []);
+                {
+                    const hooksDir = path.join(userAgentsDir, 'hooks');
+                    if (fs.existsSync(hooksDir)) {
+                        for (const file of fs.readdirSync(hooksDir).filter(f => !f.startsWith('.'))) {
+                            centralHookNames.add(file);
+                        }
+                    }
+                }
+                for (const extra of extraRepos) {
+                    const hooksDir = path.join(extra.dir, 'hooks');
+                    if (fs.existsSync(hooksDir)) {
+                        for (const file of fs.readdirSync(hooksDir).filter(f => !f.startsWith('.'))) {
+                            centralHookNames.add(file);
+                        }
+                    }
+                }
+                if (fs.existsSync(hooksTarget)) {
+                    for (const file of fs.readdirSync(hooksTarget).filter(f => !f.startsWith('.'))) {
+                        if (!centralHookNames.has(file)) {
+                            removePath(safeJoin(hooksTarget, file));
+                        }
+                    }
+                }
                 result.hooks = syncedHooks.length > 0;
                 if (syncedHooks.length > 0) {
                     recordVersionResources(agent, version, 'hooks', syncedHooks);
                 }
-                if (agent === 'claude' || agent === 'codex') {
+                // 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') {
                     registerHooksToSettings(agent, versionHome);
                 }
             }
@@ -1307,19 +1560,23 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         ? resolveSelection(selection.memory, available.memory)
         : available.memory;
     if (memoryToSync.length > 0 && COMMANDS_CAPABLE_AGENTS.includes(agent)) {
-        const centralMemory = getMemoryDir();
-        const projectMemoryDir = projectAgentsDir ? path.join(projectAgentsDir, 'memory') : null;
+        const centralMemory = getResolvedRulesDir();
+        const projectMemoryDir = projectAgentsDir ? path.join(projectAgentsDir, 'rules') : null;
+        const userMemoryDir = getUserRulesDir();
         const syncedMemory = [];
         const agentSupportsImports = !!agentConfig.capabilities.memoryImports;
         for (const mem of memoryToSync) {
-            const projectSource = projectMemoryDir ? path.join(projectMemoryDir, `${mem}.md`) : null;
-            const srcFile = projectSource && fs.existsSync(projectSource)
-                ? projectSource
-                : path.join(centralMemory, `${mem}.md`);
-            if (!fs.existsSync(srcFile))
+            const candidates = [
+                projectMemoryDir ? safeJoin(projectMemoryDir, `${mem}.md`) : null,
+                safeJoin(userMemoryDir, `${mem}.md`),
+                safeJoin(centralMemory, `${mem}.md`),
+                ...extraRepos.map((e) => safeJoin(path.join(e.dir, 'rules'), `${mem}.md`)),
+            ];
+            const srcFile = candidates.find((p) => p && fs.existsSync(p) && !fs.lstatSync(p).isSymbolicLink()) || null;
+            if (!srcFile)
                 continue;
             const targetName = mem === 'AGENTS' ? agentConfig.instructionsFile : `${mem}.md`;
-            const destFile = path.join(agentDir, targetName);
+            const destFile = safeJoin(agentDir, targetName);
             removePath(destFile);
             // For the primary memory file (AGENTS.md), agents that don't natively
             // resolve @-imports get a compiled (inlined) copy + sidecar manifest.
@@ -1338,13 +1595,43 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             recordVersionResources(agent, version, 'memory', syncedMemory);
         }
     }
-    // Apply permissions (if agent supports them)
-    // Permissions are now stored as groups in ~/.agents/permissions/groups/
+    // Apply permissions (if agent supports them).
+    // Groups live in ~/.agents/permissions/groups/. Optional recipes in
+    // ~/.agents/permissions/sets/<name>.yaml pick a subset via `includes:`.
+    // If AGENTS_PERMISSION_SET is set, we resolve that recipe and use its
+    // includes list as the group filter (intersected with groups on disk).
     const permissionGroups = discoverPermissionGroups();
     const allGroupNames = permissionGroups.map(g => g.name);
-    const permsToSync = selection
-        ? resolveSelection(selection.permissions, allGroupNames)
-        : (PERMISSIONS_CAPABLE_AGENTS.includes(agent) ? allGroupNames : []);
+    const activeSetName = getActivePermissionSetName();
+    let setFilteredGroups = null;
+    if (activeSetName) {
+        const recipe = readPermissionSetRecipe(activeSetName);
+        if (recipe) {
+            const available = new Set(allGroupNames);
+            setFilteredGroups = recipe.includes.filter(g => available.has(g));
+        }
+        else {
+            console.warn(`${PERMISSION_SET_ENV_VAR}=${activeSetName} but no recipe at ~/.agents/permissions/sets/${activeSetName}.yaml — falling back to all groups`);
+        }
+    }
+    let permsToSync;
+    if (selection) {
+        permsToSync = resolveSelection(selection.permissions, allGroupNames);
+        // If a set recipe is active, the recipe's includes list always wins —
+        // even when the caller passed an explicit array via selection. Without
+        // this intersection, `agents add`'s buildAutomaticSelection would pass
+        // every group name discovered on disk (including 99-deny), bypassing
+        // the sandbox filter.
+        if (setFilteredGroups) {
+            const filterSet = new Set(setFilteredGroups);
+            permsToSync = permsToSync.filter(g => filterSet.has(g));
+        }
+    }
+    else {
+        permsToSync = PERMISSIONS_CAPABLE_AGENTS.includes(agent)
+            ? (setFilteredGroups ?? allGroupNames)
+            : [];
+    }
     if (permsToSync.length > 0 && PERMISSIONS_CAPABLE_AGENTS.includes(agent)) {
         // Build permissions from selected groups
         const builtPerms = buildPermissionsFromGroups(permsToSync);
@@ -1386,12 +1673,12 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                     const agentsDir = path.join(agentDir, 'agents');
                     fs.mkdirSync(agentsDir, { recursive: true });
                     const transformed = transformSubagentForClaude(subagent.path);
-                    fs.writeFileSync(path.join(agentsDir, `${subagent.name}.md`), transformed);
+                    fs.writeFileSync(safeJoin(agentsDir, `${subagent.name}.md`), transformed);
                     result.subagents.push(subagent.name);
                 }
                 else if (agent === 'openclaw') {
                     // OpenClaw: copy full directory, rename AGENT.md -> AGENTS.md
-                    const targetDir = path.join(versionHome, '.openclaw', subagent.name);
+                    const targetDir = safeJoin(path.join(versionHome, '.openclaw'), subagent.name);
                     const syncResult = syncSubagentToOpenclaw(subagent.path, targetDir);
                     if (syncResult.success) {
                         result.subagents.push(subagent.name);
@@ -1427,6 +1714,10 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             recordVersionResources(agent, version, 'plugins', result.plugins);
         }
     }
+    // Write manifest after a successful full sync so the next launch can skip this work.
+    if (!selection) {
+        saveSyncManifest(agent, version, buildManifest(agent, version, available, cwd));
+    }
     return result;
 }
 /**
@@ -1712,4 +2003,3 @@ export async function promptAgentVersionSelection(availableAgents, options = {})
     }
     return { selectedAgents, versionSelections };
 }
-//# sourceMappingURL=versions.js.map