@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/dist/index.js

@@ -56,11 +56,12 @@ if (IS_DEV_BUILD) {
 }
 // Import command registrations
 import { registerPullCommand } from './commands/pull.js';
+import { registerPushCommand } from './commands/push.js';
 import { registerRepoCommands } from './commands/repo.js';
 import { registerSetupCommand, runSetup } from './commands/setup.js';
-import { registerStatusCommand } from './commands/status.js';
 import { registerFeedbackCommand } from './commands/feedback.js';
 import { registerViewCommand } from './commands/view.js';
+import { registerInspectCommand } from './commands/inspect.js';
 import { registerCommandsCommands } from './commands/commands.js';
 import { registerHooksCommands } from './commands/hooks.js';
 import { registerSkillsCommands } from './commands/skills.js';
@@ -75,6 +76,7 @@ import { registerDaemonCommands } from './commands/daemon.js';
 import { registerRoutinesCommands } from './commands/routines.js';
 import { registerRunCommand } from './commands/exec.js';
 import { registerModelsCommand } from './commands/models.js';
+import { registerDefaultsCommands } from './commands/defaults.js';
 import { registerPruneCommand } from './commands/prune.js';
 import { registerTrashCommands } from './commands/trash.js';
 import { registerDoctorCommand } from './commands/doctor.js';
@@ -86,6 +88,7 @@ import { registerSyncCommand } from './commands/sync.js';
 import { registerRefreshRulesCommand } from './commands/refresh-rules.js';
 import { registerDriveCommands } from './commands/drive.js';
 import { registerPtyCommands } from './commands/pty.js';
+import { registerTmuxCommands } from './commands/tmux.js';
 import { registerBrowserCommand } from './commands/browser.js';
 import { registerComputerCommand } from './commands/computer.js';
 import { registerProfilesCommands } from './commands/profiles.js';
@@ -99,7 +102,7 @@ import { applyGlobalHelpConventions } from './lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './commands/utils.js';
 import { AGENTS } from './lib/agents.js';
 import { getGlobalDefault, listInstalledVersions } from './lib/versions.js';
-import { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, hasAliasShadowingShim, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
+import { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, getShimsDir, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
 const program = new Command();
 program
     .name('agents')
@@ -131,6 +134,7 @@ Agent versions:
   prune cleanup [target]          Remove orphan resources and older duplicate version installs
   trash                           Inspect and restore soft-deleted version directories
   view [agent[@version]]          List versions, or inspect one in detail
+  inspect <agent>[@version]       Deep details for one agent+version — paths, capabilities, resources, drill into any kind
 
 Agent configuration (synced across versions):
   rules                           Instructions given to agents (CLAUDE.md, etc.)
@@ -148,6 +152,7 @@ Packages:
 
 Run and dispatch:
   run <agent|profile> [prompt]    Run an agent. Omit prompt for interactive mode.
+  defaults                        Configure run defaults by agent/version selector
   teams                           Coordinate multiple agents on shared work
   routines                        Run agents on a cron schedule (scheduler auto-starts)
   sessions                        Browse, search, and replay past runs (live-search in TTY; grouped by workspace)
@@ -164,7 +169,7 @@ Diagnostics:
 
 Config sync:
   drive                           Sync session history across machines via rsync
-  pull                            Clone or pull the system repo at ~/.agents-system/
+  pull                            Clone or pull the system repo at ~/.agents/.system/
   repo init --path <dir>          Scaffold your own editable repo from a template
   repo add <path|gh:user/repo>    Merge an extra repo after the system repo
 
@@ -182,7 +187,7 @@ Options:
   -V, --version                   Show version number
   -h, --help                      Show help
 
-System config lives in ~/.agents-system/. Run 'agents <command> --help' for details.
+System config lives in ~/.agents/.system/. Run 'agents <command> --help' for details.
 `;
     }
     return originalHelpInformation();
@@ -214,9 +219,12 @@ async function showWhatsNew(fromVersion, toVersion) {
             const versionMatch = line.match(/^## (\d+\.\d+\.\d+)/);
             if (versionMatch) {
                 currentVersion = versionMatch[1];
-                const isNewer = currentVersion !== fromVersion &&
-                    compareVersions(currentVersion, fromVersion) > 0;
-                inRelevantSection = isNewer;
+                // Only the range the user actually moved through: (fromVersion, toVersion].
+                // Bounding the top end matters when upgrading to a specific older
+                // version, and guards against a changelog that lists unreleased entries.
+                const inRange = compareVersions(currentVersion, fromVersion) > 0 &&
+                    compareVersions(currentVersion, toVersion) <= 0;
+                inRelevantSection = inRange;
                 if (inRelevantSection) {
                     relevantChanges.push('');
                     relevantChanges.push(chalk.bold(`v${currentVersion}`));
@@ -276,11 +284,14 @@ function saveUpdateCheck(latestVersion) {
     }
 }
 /** Fetch the exact latest npm version plus its registry integrity hash. */
-async function fetchLatestNpmPackageMetadata(timeoutMs = 5000) {
-    const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest`, {
+async function fetchNpmPackageMetadata(versionOrTag = 'latest', timeoutMs = 5000) {
+    const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/${versionOrTag}`, {
         signal: AbortSignal.timeout(timeoutMs),
     });
     if (!response.ok) {
+        if (response.status === 404) {
+            throw new Error(`${NPM_PACKAGE_NAME}@${versionOrTag} not found on npm`);
+        }
         throw new Error('Could not reach npm registry');
     }
     const data = await response.json();
@@ -335,7 +346,7 @@ async function promptUpgrade(latestVersion) {
         const { spawnSync } = await import('child_process');
         let spinner = ora('Resolving package metadata...').start();
         try {
-            const metadata = await fetchLatestNpmPackageMetadata();
+            const metadata = await fetchNpmPackageMetadata();
             spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${metadata.version}`);
             printResolvedPackage(metadata);
             const approved = await confirm({
@@ -409,10 +420,17 @@ async function checkForUpdates() {
         }
     }
 }
-async function maybeBootstrapShimIntegration(requestedCommand) {
+async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequested) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         return;
     }
+    // Pure documentation paths must never trigger interactive repair — mirrors
+    // the helpOrVersionRequested gate around ensureInitialized below. Covers
+    // both bare `agents --version` (requestedCommand === undefined) and
+    // `agents <subcommand> --help` (requestedCommand === subcommand name).
+    if (helpOrVersionRequested) {
+        return;
+    }
     if (requestedCommand === 'sync' || requestedCommand === 'refresh-rules') {
         return;
     }
@@ -447,11 +465,13 @@ async function maybeBootstrapShimIntegration(requestedCommand) {
     const shadowed = defaultAgents
         .map((agent) => ({ agent, shadowedBy: getPathShadowingExecutable(agent) }))
         .filter((item) => Boolean(item.shadowedBy));
-    // Also check for shell aliases that shadow the shim
-    const aliased = defaultAgents.filter((agent) => hasAliasShadowingShim(agent));
-    // If shims are in PATH and nothing is binary-shadowing, we're done.
     // Shell aliases that call the same command with extra flags are intentional
-    // customization and don't break shim integration.
+    // customization and don't break shim integration — `addShimsToPath` cannot
+    // touch them, so they don't belong in the repair prompt. We previously
+    // computed an `aliased` list here and inserted it into `affected`, which
+    // contradicted the comment below and surfaced false positives (e.g. an
+    // earlier `alias codex=...` cancelled by a later `unalias codex` was
+    // reported because the detector did a static rc-file regex).
     if (shadowed.length === 0 && isShimsInPath()) {
         return;
     }
@@ -468,14 +488,11 @@ async function maybeBootstrapShimIntegration(requestedCommand) {
     for (const { agent, shadowedBy } of shadowed) {
         affected.push(`${AGENTS[agent].cliCommand} -> ${shadowedBy}`);
     }
-    for (const agent of aliased) {
-        if (!shadowed.some((s) => s.agent === agent)) {
-            affected.push(`${AGENTS[agent].cliCommand} (alias)`);
-        }
-    }
     if (affected.length === 0) {
-        // PATH issue - show all installed agents
-        affected.push(...installedAgents.map((agent) => AGENTS[agent].cliCommand));
+        // Pure PATH-not-loaded case: rc may already have the shim block, but the
+        // running shell hasn't sourced it. Don't list agents here — they aren't
+        // broken; only the PATH is stale. The prompt + post-message handle it.
+        affected.push('PATH entry missing');
     }
     const shouldRepair = await confirm({
         message: `Repair shim integration now? ${affected.join(', ')}`,
@@ -494,15 +511,38 @@ async function maybeBootstrapShimIntegration(requestedCommand) {
     if (!pathResult.success) {
         console.log(chalk.yellow('Could not repair shim PATH setup automatically.'));
         console.log(chalk.gray(pathResult.error || getPathSetupInstructions()));
+        // Write the sentinel even on failure — otherwise an unwritable rc file
+        // re-prompts every invocation in the same shell. The user opens a new
+        // terminal (new PPID) to retry.
+        try {
+            fs.writeFileSync(sentinelPath, '1');
+        }
+        catch { /* best-effort */ }
         return;
     }
+    // When the rc file already has the canonical shim block, `addShimsToPath`
+    // is a no-op — re-emitting produced byte-identical content. In this branch
+    // the user clicked "Yes" but nothing changed on disk, AND the underlying
+    // cause (a real binary shadow, or a stale shell PATH) is unaffected by
+    // this command. Be honest about it and point at the actual action.
     if (pathResult.alreadyPresent) {
-        console.log(chalk.yellow('Shim PATH entry is already in your shell config, but this shell has not reloaded it yet.'));
+        if (shadowed.length > 0) {
+            const targets = shadowed
+                .map(({ agent, shadowedBy }) => `  ${AGENTS[agent].cliCommand}: ${shadowedBy}`)
+                .join('\n');
+            console.log(chalk.yellow('Repair could not change anything — the shim is shadowed by another binary on PATH:'));
+            console.log(chalk.gray(targets));
+            console.log(chalk.gray(`Fix it by removing or reordering that binary, or making sure ${getShimsDir()} appears earlier in PATH than its parent dir.`));
+        }
+        else {
+            console.log(chalk.yellow(`Shim PATH entry is already in ~/${pathResult.rcFile} — this shell just needs to reload it.`));
+            console.log(chalk.gray(`Run: source ~/${pathResult.rcFile}   (or open a new terminal)`));
+        }
     }
     else {
         console.log(chalk.green(`Repaired shim PATH setup in ~/${pathResult.rcFile}`));
+        console.log(chalk.gray(getPathSetupInstructions()));
     }
-    console.log(chalk.gray(getPathSetupInstructions()));
     try {
         fs.writeFileSync(sentinelPath, '1');
     }
@@ -510,7 +550,7 @@ async function maybeBootstrapShimIntegration(requestedCommand) {
 }
 // Register all commands
 registerViewCommand(program);
-registerStatusCommand(program);
+registerInspectCommand(program);
 registerFeedbackCommand(program);
 registerCommandsCommands(program);
 registerHooksCommands(program);
@@ -551,6 +591,7 @@ registerPackagesCommands(program);
 registerDaemonCommands(program);
 registerRoutinesCommands(program);
 registerRunCommand(program);
+registerDefaultsCommands(program);
 registerModelsCommand(program);
 registerPruneCommand(program);
 registerTrashCommands(program);
@@ -577,6 +618,7 @@ registerFactoryCommands(program);
 registerUsageCommand(program);
 registerAliasCommand(program);
 registerPtyCommands(program);
+registerTmuxCommands(program);
 registerBrowserCommand(program);
 registerComputerCommand(program);
 // Deprecated 'jobs' and 'cron' aliases for 'routines'
@@ -594,26 +636,31 @@ for (const alias of ['jobs', 'cron']) {
 }
 program
     .command('upgrade')
-    .description('Upgrade agents-cli to the latest version')
+    .description('Upgrade agents-cli to the latest version (or a specific [version])')
+    .argument('[version]', 'Target version or dist-tag to install (default: latest)')
     .option('-y, --yes', 'Install without an interactive confirmation prompt')
-    .action(async (options) => {
-    let spinner = ora('Checking for updates...').start();
+    .action(async (version, options) => {
+    const target = version ?? 'latest';
+    let spinner = ora(version ? `Resolving ${NPM_PACKAGE_NAME}@${target}...` : 'Checking for updates...').start();
     try {
-        const metadata = await fetchLatestNpmPackageMetadata();
-        const latestVersion = metadata.version;
-        if (latestVersion === VERSION) {
-            spinner.succeed(`Already on latest version (${VERSION})`);
+        const metadata = await fetchNpmPackageMetadata(target);
+        const resolvedVersion = metadata.version;
+        if (resolvedVersion === VERSION) {
+            spinner.succeed(`Already on ${VERSION}`);
             return;
         }
-        if (compareVersions(latestVersion, VERSION) <= 0) {
-            spinner.succeed(`Already ahead of latest (${VERSION} >= ${latestVersion})`);
+        // For `latest` (no explicit version) skip when already ahead. When a
+        // version is named explicitly, honor it even if it's a downgrade.
+        if (!version && compareVersions(resolvedVersion, VERSION) <= 0) {
+            spinner.succeed(`Already ahead of latest (${VERSION} >= ${resolvedVersion})`);
             return;
         }
-        spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${latestVersion}`);
+        const direction = compareVersions(resolvedVersion, VERSION) < 0 ? 'Downgrade' : 'Upgrade';
+        spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${resolvedVersion}`);
         printResolvedPackage(metadata);
         if (isInteractiveTerminal() && !options.yes) {
             const approved = await confirm({
-                message: `Install ${NPM_PACKAGE_NAME}@${latestVersion}?`,
+                message: `Install ${NPM_PACKAGE_NAME}@${resolvedVersion}?`,
                 default: false,
             });
             if (!approved) {
@@ -621,17 +668,21 @@ program
                 return;
             }
         }
-        spinner = ora(`Upgrading ${VERSION} -> ${latestVersion}...`).start();
+        spinner = ora(`${direction === 'Downgrade' ? 'Downgrading' : 'Upgrading'} ${VERSION} -> ${resolvedVersion}...`).start();
         await installResolvedPackage(metadata);
-        spinner.succeed(`Upgraded to ${latestVersion}`);
-        await showWhatsNew(VERSION, latestVersion);
+        spinner.succeed(`${direction}d to ${resolvedVersion}`);
+        // Only show the changelog for a genuine upgrade range.
+        if (compareVersions(resolvedVersion, VERSION) > 0) {
+            await showWhatsNew(VERSION, resolvedVersion);
+        }
     }
     catch (err) {
         spinner.fail('Upgrade failed');
-        console.log(chalk.gray('Run manually: agents upgrade --yes'));
+        console.log(chalk.gray(`Run manually: agents upgrade ${version ? version + ' ' : ''}--yes`));
     }
 });
 registerPullCommand(program);
+registerPushCommand(program);
 registerRepoCommands(program);
 registerSetupCommand(program);
 applyGlobalHelpConventions(program);
@@ -742,6 +793,20 @@ const SETUP_EXEMPT_COMMANDS = new Set(['setup', 'help']);
 // Help and version output are pure documentation — they must never gate on
 // setup, otherwise `agents <cmd> --help` becomes useless on a fresh box.
 const helpOrVersionRequested = passedArgs.some((arg) => arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V');
+// Fold legacy ~/.agents-system/ into ~/.agents/.system/ BEFORE ensureInitialized
+// runs. ensureInitialized checks for .git inside the new path; if the user is
+// upgrading from a layout where .git lives under the legacy path, the check
+// would fail and exit before the migrator ever runs. Also runs outside the
+// sentinel guard below because the sentinel was set by pre-fold releases and
+// would otherwise skip this step on every existing install. Idempotent —
+// no-ops when legacy is missing or already a symlink.
+if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
+    try {
+        const { foldLegacySystemRepo } = await import('./lib/migrate.js');
+        foldLegacySystemRepo();
+    }
+    catch { /* must never block CLI startup */ }
+}
 if (!firstRun &&
     requestedCommand &&
     !SETUP_EXEMPT_COMMANDS.has(requestedCommand) &&
@@ -783,7 +848,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
     catch { /* migration must never block CLI startup */ }
 }
 try {
-    await maybeBootstrapShimIntegration(requestedCommand);
+    await maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequested);
     await program.parseAsync();
 }
 catch (err) {

package/dist/lib/agents.d.ts

@@ -23,16 +23,6 @@ export declare const GEMINI_HOOKS_MIN_VERSION = "0.26.0";
 export declare const AGENTS: Record<AgentId, AgentConfig>;
 /** All registered agent IDs derived from the AGENTS registry. */
 export declare const ALL_AGENT_IDS: AgentId[];
-/** Agents that support MCP (Model Context Protocol) server integration. */
-export declare const MCP_CAPABLE_AGENTS: AgentId[];
-/** Agents that support skills (SKILL.md + rules/ bundles). */
-export declare const SKILLS_CAPABLE_AGENTS: AgentId[];
-/** Agents that support file-based slash commands. */
-export declare const COMMANDS_CAPABLE_AGENTS: AgentId[];
-/** Agents that support event hooks (pre/post lifecycle callbacks). */
-export declare const HOOKS_CAPABLE_AGENTS: readonly AgentId[];
-/** Agents that support the plugin system. */
-export declare const PLUGINS_CAPABLE_AGENTS: AgentId[];
 /** Get the chalk color function for an agent. Works for any AgentId or SessionAgentId. */
 export declare function colorAgent(agentId: string): (s: string) => string;
 /** Return the agent's display name, colored. */
@@ -59,6 +49,13 @@ export interface UnmanagedInstall {
     configDir: string;
     version: string | null;
 }
+/**
+ * Agents that `agents setup` probes for pre-existing native installations
+ * (i.e., a config dir present before agents-cli took over). Add an agent here
+ * once its `cliCommand` reports a usable `--version` and its session dir is
+ * wired into `getSessionDir`.
+ */
+export declare const UNMANAGED_DETECTION_CANDIDATES: AgentId[];
 /**
  * Detect existing agent installations that are NOT yet managed by agents-cli.
  * Returns agents whose config dir exists as a real directory (not a symlink).
@@ -68,6 +65,22 @@ export declare function getUnmanagedAgentInstalls(): Promise<UnmanagedInstall[]>
 export declare function ensureCommandsDir(agentId: AgentId): void;
 /** Create the agent's skills directory if it does not exist. */
 export declare function ensureSkillsDir(agentId: AgentId): void;
+/**
+ * The agent's config-dir name relative to $HOME — e.g. '.claude',
+ * '.gemini/antigravity-cli', '.config/amp', '.kimi-code'.
+ *
+ * Path segment to join onto a (version) home root when locating an agent's
+ * commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong for
+ * every agent whose config dir is nested or under ~/.config — antigravity
+ * (~/.gemini/antigravity-cli), amp (~/.config/amp), goose (~/.config/goose),
+ * kimi (~/.kimi-code). Mirrors the shim configDirName derivation in shims.ts.
+ *
+ * Relativized against the module-level HOME constant (the same value used to
+ * build every `configDir`), NOT a fresh `os.homedir()` — so the result stays a
+ * clean relative name even when HOME is overridden after module load (tests,
+ * sandboxes). Using `os.homedir()` here would yield `../../real/home/.claude`.
+ */
+export declare function agentConfigDirName(agentId: AgentId): string;
 /** Account identity and billing information extracted from an agent's auth config. */
 export interface AccountInfo {
     accountKey: string | null;

package/dist/lib/agents.js

@@ -203,7 +203,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, modes: ['plan', 'edit', 'auto', 'skip'], rulesImports: true },
+        capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, subagents: true, rules: { file: 'CLAUDE.md' }, workflows: true, modes: ['plan', 'edit', 'auto', 'skip'], rulesImports: true },
     },
     // codex hooks: gated to >= 0.116.0 (introduced [features] codex_hooks flag).
     codex: {
@@ -222,7 +222,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, modes: ['plan', 'edit', 'skip'] },
+        capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'skip'] },
     },
     gemini: {
         id: 'gemini',
@@ -241,7 +241,7 @@ export const AGENTS = {
         supportsHooks: true,
         nativeAgentsSkillsDir: true,
         // gemini hooks: shipped in v0.26.0 (Jan 2026); older binaries silently ignore the `hooks` key.
-        capabilities: { hooks: { since: '0.26.0' }, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit', 'skip'], rulesImports: true },
+        capabilities: { hooks: { since: '0.26.0' }, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'GEMINI.md' }, workflows: false, modes: ['plan', 'edit', 'skip'], rulesImports: true },
     },
     cursor: {
         id: 'cursor',
@@ -259,7 +259,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['edit', 'skip'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: '.cursorrules' }, workflows: false, modes: ['edit', 'skip'] },
     },
     opencode: {
         id: 'opencode',
@@ -276,7 +276,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit'] },
     },
     openclaw: {
         id: 'openclaw',
@@ -293,7 +293,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '{{ARGUMENTS}}',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, allowlist: false, skills: true, commands: false, plugins: true, modes: ['plan', 'edit', 'skip'] },
+        capabilities: { hooks: true, mcp: true, allowlist: false, skills: true, commands: false, plugins: true, subagents: true, rules: { file: 'workspace/AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'skip'] },
     },
     copilot: {
         id: 'copilot',
@@ -310,7 +310,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit', 'auto', 'skip'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'auto', 'skip'] },
     },
     amp: {
         id: 'amp',
@@ -327,7 +327,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit'] },
     },
     kiro: {
         id: 'kiro',
@@ -345,7 +345,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['edit'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['edit'] },
     },
     goose: {
         id: 'goose',
@@ -363,7 +363,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: false, commands: false, plugins: false, modes: ['edit'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: false, commands: false, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['edit'] },
     },
     roo: {
         id: 'roo',
@@ -381,7 +381,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit'] },
     },
     // Google Antigravity CLI (`agy`) — official replacement for Gemini CLI as of IO 2026.
     // configDir nests inside `~/.gemini/` since agy shares the parent dir with the Gemini
@@ -408,7 +408,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '{{args}}',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, modes: ['edit', 'skip'], rulesImports: false },
+        capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['edit', 'skip'], rulesImports: false },
     },
     // xAI Grok Build CLI (`grok`) — early beta, SuperGrok Heavy. Auth via OAuth on
     // first launch, or XAI_API_KEY env var for headless. MCP servers configured inline
@@ -439,23 +439,56 @@ export const AGENTS = {
             skills: true,
             commands: false, // covered by skills
             plugins: true,
+            subagents: false,
+            rules: { file: 'AGENTS.md' },
+            workflows: false,
             modes: ['plan', 'edit', 'skip'],
             rulesImports: true,
         },
     },
+    // Kimi Code CLI (`kimi`) — Moonshot AI coding agent.
+    // Install: `curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash`
+    //    or: `npm install -g @moonshot-ai/kimi-code`
+    // Config: `~/.kimi-code/config.toml`, `~/.kimi-code/mcp.json`,
+    //         `~/.kimi-code/skills/`, `~/.kimi-code/hooks/`
+    kimi: {
+        id: 'kimi',
+        name: 'Kimi',
+        color: 'magentaBright',
+        cliCommand: 'kimi',
+        npmPackage: '@moonshot-ai/kimi-code',
+        installScript: 'curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash',
+        configDir: path.join(HOME, '.kimi-code'),
+        commandsDir: '',
+        commandsSubdir: '',
+        skillsDir: path.join(HOME, '.kimi-code', 'skills'),
+        hooksDir: path.join(HOME, '.kimi-code', 'hooks'),
+        instructionsFile: 'AGENTS.md',
+        format: 'markdown',
+        variableSyntax: '$ARGUMENTS',
+        supportsHooks: true,
+        capabilities: {
+            hooks: true,
+            mcp: true,
+            allowlist: true,
+            skills: true,
+            commands: false,
+            plugins: true,
+            subagents: false,
+            rules: { file: 'AGENTS.md' },
+            workflows: false,
+            modes: ['plan', 'edit', 'auto', 'skip'],
+            rulesImports: false,
+        },
+    },
 };
 /** All registered agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
-/** Agents that support MCP (Model Context Protocol) server integration. */
-export const MCP_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.mcp);
-/** Agents that support skills (SKILL.md + rules/ bundles). */
-export const SKILLS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.skills);
-/** Agents that support file-based slash commands. */
-export const COMMANDS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.commands);
-/** Agents that support event hooks (pre/post lifecycle callbacks). */
-export const HOOKS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.hooks !== false);
-/** Agents that support the plugin system. */
-export const PLUGINS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.plugins !== false);
+// Capability-filtered agent lists used to live here as `*_CAPABLE_AGENTS`
+// constants. They were a frequent source of silent-skip bugs (e.g. grok
+// rules sync gated on `COMMANDS_CAPABLE_AGENTS`). Use `capableAgents(cap)`
+// from `./capabilities.js` instead — it consults the AgentConfig matrix
+// directly, so a single source of truth drives every gate.
 /** Get the chalk color function for an agent. Works for any AgentId or SessionAgentId. */
 export function colorAgent(agentId) {
     const agent = AGENTS[agentId];
@@ -610,14 +643,26 @@ export function isConfigured(agentId) {
     const agent = AGENTS[agentId];
     return fs.existsSync(agent.configDir);
 }
+/**
+ * Agents that `agents setup` probes for pre-existing native installations
+ * (i.e., a config dir present before agents-cli took over). Add an agent here
+ * once its `cliCommand` reports a usable `--version` and its session dir is
+ * wired into `getSessionDir`.
+ */
+export const UNMANAGED_DETECTION_CANDIDATES = [
+    'claude',
+    'codex',
+    'gemini',
+    'grok',
+    'copilot',
+];
 /**
  * Detect existing agent installations that are NOT yet managed by agents-cli.
  * Returns agents whose config dir exists as a real directory (not a symlink).
  */
 export async function getUnmanagedAgentInstalls() {
     const unmanaged = [];
-    const candidates = ['claude', 'codex', 'gemini', 'grok'];
-    for (const agentId of candidates) {
+    for (const agentId of UNMANAGED_DETECTION_CANDIDATES) {
         const agent = AGENTS[agentId];
         try {
             const stat = fs.lstatSync(agent.configDir);
@@ -646,6 +691,24 @@ export function ensureSkillsDir(agentId) {
         fs.mkdirSync(agent.skillsDir, { recursive: true });
     }
 }
+/**
+ * The agent's config-dir name relative to $HOME — e.g. '.claude',
+ * '.gemini/antigravity-cli', '.config/amp', '.kimi-code'.
+ *
+ * Path segment to join onto a (version) home root when locating an agent's
+ * commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong for
+ * every agent whose config dir is nested or under ~/.config — antigravity
+ * (~/.gemini/antigravity-cli), amp (~/.config/amp), goose (~/.config/goose),
+ * kimi (~/.kimi-code). Mirrors the shim configDirName derivation in shims.ts.
+ *
+ * Relativized against the module-level HOME constant (the same value used to
+ * build every `configDir`), NOT a fresh `os.homedir()` — so the result stays a
+ * clean relative name even when HOME is overridden after module load (tests,
+ * sandboxes). Using `os.homedir()` here would yield `../../real/home/.claude`.
+ */
+export function agentConfigDirName(agentId) {
+    return path.relative(HOME, AGENTS[agentId].configDir);
+}
 /** Return the email address associated with the agent's auth config, or null. */
 export async function getAccountEmail(agentId, home) {
     const info = await getAccountInfo(agentId, home);
@@ -1280,7 +1343,7 @@ export function getMcpConfigPathForHome(agentId, home) {
         case 'grok':
             return path.join(home, '.grok', 'config.toml');
         default:
-            return path.join(home, `.${agentId}`, 'settings.json');
+            return path.join(home, agentConfigDirName(agentId), 'settings.json');
     }
 }
 /**

package/dist/lib/auto-pull-worker.d.ts

@@ -5,7 +5,7 @@
  * For the user repo + enabled extras: `git fetch` + write a status marker the foreground
  * CLI surfaces on its next invocation.
  *
- * Per-repo lock files at ~/.agents-system/.fetch/<alias>.lock prevent concurrent fetches.
+ * Per-repo lock files at ~/.agents/.system/.fetch/<alias>.lock prevent concurrent fetches.
  * Lock mtime under 5 min => skip (another invocation already in flight).
  */
 export {};

package/dist/lib/auto-pull-worker.js

@@ -5,7 +5,7 @@
  * For the user repo + enabled extras: `git fetch` + write a status marker the foreground
  * CLI surfaces on its next invocation.
  *
- * Per-repo lock files at ~/.agents-system/.fetch/<alias>.lock prevent concurrent fetches.
+ * Per-repo lock files at ~/.agents/.system/.fetch/<alias>.lock prevent concurrent fetches.
  * Lock mtime under 5 min => skip (another invocation already in flight).
  */
 import * as fs from 'fs';
@@ -15,7 +15,7 @@ import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, getFetchCac
 import { lockFilePath, statusFilePath } from './auto-pull.js';
 const LOCK_TTL_MS = 5 * 60 * 1000;
 /**
- * Background auto-pull of ~/.agents-system/ is off by default. When enabled it
+ * Background auto-pull of ~/.agents/.system/ is off by default. When enabled it
  * silently fast-forwards a tracked source tree that the CLI then reads as a
  * source of skills, hooks, install manifests, and commands — anyone with push
  * access to that upstream gets remote code execution on every user the next