@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/lib/agents.js

@@ -22,8 +22,10 @@ import { execFileShellSpec } from './platform/index.js';
 import { latestFileMtimeMs } from './fs-walk.js';
 import { damerauLevenshtein } from './fuzzy.js';
 import { getCacheDir, getVersionsDir, getShimsDir, getHistoryDir, getCliVersionCachePath } from './state.js';
-import { resolveVersion, getVersionHomePath, getBinaryPath } from './versions.js';
+import { resolveVersion, getVersionHomePath, getBinaryPath } from './installations/versions.js';
 import { supports } from './capabilities.js';
+import { MCP_TARGETS } from './mcp-registry.js';
+import { VERSION_RE } from './agent-spec/primitives.js';
 const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
 /**
@@ -239,6 +241,14 @@ export const AGENTS = {
     claude: {
         id: 'claude',
         name: 'Claude',
+        sessionDir: ['.claude', 'projects'],
+        sessionFileExt: '.jsonl',
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'scope',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'magenta',
         cliCommand: 'claude',
         npmPackage: '@anthropic-ai/claude-code',
@@ -263,6 +273,14 @@ export const AGENTS = {
     codex: {
         id: 'codex',
         name: 'Codex',
+        sessionDir: ['.codex', 'sessions'],
+        sessionFileExt: '.jsonl',
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'url',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'green',
         cliCommand: 'codex',
         npmPackage: '@openai/codex',
@@ -284,6 +302,14 @@ export const AGENTS = {
     gemini: {
         id: 'gemini',
         name: 'Gemini',
+        sessionDir: ['.gemini', 'tmp'],
+        sessionFileExt: '.json',
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'blue',
         cliCommand: 'gemini',
         npmPackage: '@google/gemini-cli',
@@ -316,6 +342,14 @@ export const AGENTS = {
     cursor: {
         id: 'cursor',
         name: 'Cursor',
+        sessionDir: null,
+        sessionFileExt: null,
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'cyan',
         cliCommand: 'cursor-agent',
         npmPackage: '',
@@ -351,6 +385,14 @@ export const AGENTS = {
     opencode: {
         id: 'opencode',
         name: 'OpenCode',
+        sessionDir: null,
+        sessionFileExt: null,
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'yellowBright',
         cliCommand: 'opencode',
         npmPackage: 'opencode-ai',
@@ -380,6 +422,14 @@ export const AGENTS = {
     pi: {
         id: 'pi',
         name: 'Pi',
+        sessionDir: null,
+        sessionFileExt: null,
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'magenta',
         cliCommand: 'omp',
         npmPackage: '@oh-my-pi/pi-coding-agent',
@@ -411,6 +461,14 @@ export const AGENTS = {
     openclaw: {
         id: 'openclaw',
         name: 'OpenClaw',
+        sessionDir: null,
+        sessionFileExt: null,
+        versionStdoutMatch: 'openclaw',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'redBright',
         cliCommand: 'openclaw',
         npmPackage: 'openclaw',
@@ -443,6 +501,14 @@ export const AGENTS = {
     copilot: {
         id: 'copilot',
         name: 'Copilot',
+        sessionDir: ['.copilot', 'session-state'],
+        sessionFileExt: '.jsonl',
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'whiteBright',
         cliCommand: 'copilot',
         npmPackage: '@github/copilot',
@@ -470,6 +536,14 @@ export const AGENTS = {
     amp: {
         id: 'amp',
         name: 'Amp',
+        sessionDir: null,
+        sessionFileExt: null,
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'blueBright',
         cliCommand: 'amp',
         npmPackage: '@sourcegraph/amp',
@@ -488,6 +562,14 @@ export const AGENTS = {
     kiro: {
         id: 'kiro',
         name: 'Kiro',
+        sessionDir: null,
+        sessionFileExt: null,
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'greenBright',
         cliCommand: 'kiro-cli',
         npmPackage: '',
@@ -513,6 +595,14 @@ export const AGENTS = {
     goose: {
         id: 'goose',
         name: 'Goose',
+        sessionDir: null,
+        sessionFileExt: null,
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'magentaBright',
         cliCommand: 'goose',
         npmPackage: '',
@@ -534,13 +624,14 @@ export const AGENTS = {
         supportsHooks: true,
         // Plugins: Open Plugins under ~/.agents/plugins/<name>/ (same layout as
         // agents-cli source). Version isolation copies into versionHome/.agents/plugins/.
-        // Workflows sync as Goose recipe YAML; permissions sync to permission.yaml.
+        // Workflows sync as Goose recipe YAML. Permissions are NOT supported:
+        // permission.yaml gates whole tools, so canonical rules cannot round-trip.
         // Commands: a Goose slash command is a recipe YAML under
         // ~/.config/goose/commands/<name>.yaml, registered in ~/.config/goose/config.yaml
         // under `slash_commands: [{ command, recipe_path }]` (see goose-commands.ts).
         // Subagents: recipe YAML named agents under ~/.config/goose/agents/<name>.yaml
         // (goose auto-discovers and delegates to them by name in autonomous mode).
-        capabilities: { hooks: { since: '1.34.0' }, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: { since: '1.25.0' }, commands: true, plugins: true, subagents: true, rules: { file: 'AGENTS.md' }, workflows: true, memory: false, modes: ['edit'], interactiveRepl: true },
+        capabilities: { hooks: { since: '1.34.0' }, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: false, skills: { since: '1.25.0' }, commands: true, plugins: true, subagents: true, rules: { file: 'AGENTS.md' }, workflows: true, memory: false, modes: ['edit'], interactiveRepl: true },
     },
     // 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
@@ -554,6 +645,14 @@ export const AGENTS = {
     antigravity: {
         id: 'antigravity',
         name: 'Antigravity',
+        sessionDir: null,
+        sessionFileExt: null,
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'blueBright',
         cliCommand: 'agy',
         npmPackage: '',
@@ -582,6 +681,14 @@ export const AGENTS = {
     grok: {
         id: 'grok',
         name: 'Grok',
+        sessionDir: ['.grok', 'sessions'],
+        sessionFileExt: '.json',
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'grok-downloads',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'cyanBright',
         cliCommand: 'grok',
         npmPackage: '',
@@ -631,6 +738,14 @@ export const AGENTS = {
     kimi: {
         id: 'kimi',
         name: 'Kimi',
+        sessionDir: null,
+        sessionFileExt: null,
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'magentaBright',
         cliCommand: 'kimi',
         npmPackage: '@moonshot-ai/kimi-code',
@@ -717,6 +832,14 @@ export const AGENTS = {
     droid: {
         id: 'droid',
         name: 'Droid',
+        sessionDir: ['.factory', 'sessions'],
+        sessionFileExt: '.jsonl',
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'yellowBright',
         cliCommand: 'droid',
         npmPackage: '',
@@ -760,6 +883,14 @@ export const AGENTS = {
     hermes: {
         id: 'hermes',
         name: 'Hermes',
+        sessionDir: null,
+        sessionFileExt: null,
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'config',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'yaml-mcp_servers',
         color: 'cyanBright',
         cliCommand: 'hermes',
         npmPackage: '',
@@ -817,6 +948,14 @@ export const AGENTS = {
     muse: {
         id: 'muse',
         name: 'Muse',
+        sessionDir: ['.local', 'share', 'muse', 'sessions'],
+        sessionFileExt: '.jsonl',
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'blueBright',
         cliCommand: 'muse',
         npmPackage: '',
@@ -886,6 +1025,14 @@ export const AGENTS = {
     warp: {
         id: 'warp',
         name: 'Warp',
+        sessionDir: null,
+        sessionFileExt: null,
+        versionStdoutMatch: 'semver',
+        unmanagedBinary: 'path',
+        mcpRegister: 'cli',
+        mcpAddHttp: 'transport',
+        mcpAddStdio: 'simple',
+        mcpConfigWrite: 'json-mcpServers',
         color: 'blueBright',
         cliCommand: 'warp',
         npmPackage: '',
@@ -948,7 +1095,9 @@ export const ALL_AGENT_IDS = Object.keys(AGENTS);
 export const ROUTINE_AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
     codex: ['codex', 'exec', '{prompt}', '--json'],
-    gemini: ['gemini', '{prompt}', '--output-format', 'stream-json'],
+    // gemini is hard-deprecated (Antigravity replaced it) — no routine target. A
+    // legacy gemini routine now fails validateJob loud instead of firing a
+    // retired backend; the id survives only for reading old sessions/config.
     cursor: ['cursor-agent', '-p', '{prompt}', '--output-format', 'stream-json'],
     kimi: ['kimi', '--prompt', '{prompt}', '--output-format', 'stream-json'],
     droid: ['droid', 'exec', '{prompt}', '-o', 'stream-json'],
@@ -987,7 +1136,9 @@ export function isSelfUpdatingAgent(agent) {
     return !cfg.npmPackage && !!cfg.installScript && !cfg.installScript.includes('VERSION');
 }
 export function isAgentHardDeprecated(agent) {
-    return AGENTS[agent].deprecated?.hard === true;
+    // Tolerate ids outside the registry (legacy YAML, test fixtures): an unknown
+    // agent is not hard-deprecated — its own validation rejects it elsewhere.
+    return AGENTS[agent]?.deprecated?.hard === true;
 }
 // Capability-filtered agent lists used to live here as `*_CAPABLE_AGENTS`
 // constants. They were a frequent source of silent-skip bugs (e.g. grok
@@ -1044,14 +1195,11 @@ async function getCachedVersionForBinary(agentId, binaryPath) {
     let version = null;
     try {
         const { stdout } = await execFileAsync(agent.cliCommand, ['--version'], { timeout: 3000 });
-        if (agentId === 'openclaw') {
-            const match = stdout.match(/openclaw\/(\d+\.\d+\.\d+)/);
-            version = match ? match[1] : stdout.trim();
-        }
-        else {
-            const match = stdout.match(/(\d+\.\d+\.\d+)/);
-            version = match ? match[1] : stdout.trim();
-        }
+        const versionRe = agent.versionStdoutMatch === 'openclaw'
+            ? /openclaw\/(\d+\.\d+\.\d+)/
+            : /(\d+\.\d+\.\d+)/;
+        const match = stdout.match(versionRe);
+        version = match ? match[1] : stdout.trim();
     }
     catch {
         /* version command failed */
@@ -1122,8 +1270,9 @@ export async function getCliState(agentId) {
  */
 export async function getUnmanagedCliState(agentId) {
     const agent = AGENTS[agentId];
-    // Special case for grok: it manages its own binaries in ~/.grok/downloads/
-    if (agentId === 'grok') {
+    // Grok (and any future harness with unmanagedBinary: 'grok-downloads')
+    // keeps versioned binaries under ~/.grok/downloads/, not on PATH.
+    if (agent.unmanagedBinary === 'grok-downloads') {
         const grokBin = resolveGrokBinary();
         if (!grokBin) {
             return { installed: false, version: null, path: null };
@@ -1158,19 +1307,10 @@ export async function getAllCliStates() {
 }
 /**
  * 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`.
+ * (i.e., a config dir present before agents-cli took over). Derived from
+ * `sessionDir` so a new harness cannot be walkable yet missing from setup.
  */
-export const UNMANAGED_DETECTION_CANDIDATES = [
-    'claude',
-    'codex',
-    'gemini',
-    'grok',
-    'copilot',
-    'droid',
-    'muse',
-];
+export const UNMANAGED_DETECTION_CANDIDATES = ALL_AGENT_IDS.filter((id) => AGENTS[id].sessionDir !== null);
 /**
  * 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).
@@ -2233,45 +2373,12 @@ function writeLastActiveCacheFile(cache, cachePath) {
 }
 /** Return the root directory where the agent stores session files, or null if unknown. */
 function getSessionDir(agentId, base) {
-    switch (agentId) {
-        case 'claude':
-            return path.join(base, '.claude', 'projects');
-        case 'codex':
-            return path.join(base, '.codex', 'sessions');
-        case 'gemini':
-            return path.join(base, '.gemini', 'tmp');
-        case 'grok':
-            return path.join(base, '.grok', 'sessions');
-        case 'copilot':
-            // Copilot persists sessions at ~/.copilot/session-state/<id>/events.jsonl.
-            // The events.jsonl is the canonical NDJSON event stream per session.
-            return path.join(base, '.copilot', 'session-state');
-        case 'droid':
-            return path.join(base, '.factory', 'sessions');
-        case 'muse':
-            // Muse sessions live under XDG data, not the config dir:
-            // ~/.local/share/muse/sessions/YYYY/MM/DD/<uuid>/session.jsonl
-            return path.join(base, '.local', 'share', 'muse', 'sessions');
-        default:
-            return null;
-    }
+    const rel = AGENTS[agentId].sessionDir;
+    return rel ? path.join(base, ...rel) : null;
 }
 /** Return the file extension used for session files by the given agent. */
 function getSessionExtension(agentId) {
-    switch (agentId) {
-        case 'claude':
-        case 'codex':
-        case 'copilot':
-        case 'droid':
-        case 'muse':
-            return '.jsonl';
-        case 'gemini':
-            return '.json';
-        case 'grok':
-            return '.json'; // sessions contain summary.json, events.jsonl, etc.
-        default:
-            return null;
-    }
+    return AGENTS[agentId].sessionFileExt;
 }
 /**
  * Quick count of session files for an agent (without full DB scan).
@@ -2350,7 +2457,7 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
     if (transport === 'http' && options?.headers && Object.keys(options.headers).length > 0 && !supports(agentId, 'mcpHeaders').ok) {
         return { success: false, error: 'skipped: HTTP MCP headers are only supported for Claude registration' };
     }
-    if (agentId === 'hermes') {
+    if (agent.mcpRegister === 'config') {
         try {
             writeMcpToConfig(agentId, name, command, scope, transport, options?.home);
             return { success: true };
@@ -2367,7 +2474,7 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
         const bin = options?.binary || agent.cliCommand;
         let args;
         if (transport === 'http') {
-            if (agentId === 'codex') {
+            if (agent.mcpAddHttp === 'url') {
                 args = ['mcp', 'add', name, '--url', command];
             }
             else {
@@ -2375,7 +2482,7 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
                 args = ['mcp', 'add', '--transport', 'http', '--scope', scope, name, command, ...headerArgs];
             }
         }
-        else if (agentId === 'claude') {
+        else if (agent.mcpAddStdio === 'scope') {
             const commandArgs = splitCommandLine(command);
             args = ['mcp', 'add', '--transport', transport, '--scope', scope, name, '--', ...commandArgs];
         }
@@ -2404,7 +2511,7 @@ export async function unregisterMcp(agentId, name, options) {
     if (!supports(agentId, 'mcp').ok) {
         return { success: false, error: 'Agent does not support MCP' };
     }
-    if (agentId === 'hermes') {
+    if (agent.mcpRegister === 'config') {
         try {
             removeMcpFromConfig(agentId, name, options?.home);
             return { success: true };
@@ -2514,7 +2621,7 @@ function readJsonConfig(configPath) {
 function writeMcpToConfig(agentId, name, command, scope, transport, home) {
     const configPath = scopedMcpConfigPath(agentId, scope, home);
     const entry = mcpEntryFromCommand(command, transport);
-    if (agentId === 'hermes') {
+    if (AGENTS[agentId].mcpConfigWrite === 'yaml-mcp_servers') {
         const config = readYamlConfig(configPath);
         if (!config.mcp_servers || typeof config.mcp_servers !== 'object' || Array.isArray(config.mcp_servers)) {
             config.mcp_servers = {};
@@ -2536,7 +2643,7 @@ function removeMcpFromConfig(agentId, name, home) {
     const configPath = userMcpConfigPath(agentId, home);
     if (!fs.existsSync(configPath))
         return;
-    if (agentId === 'hermes') {
+    if (AGENTS[agentId].mcpConfigWrite === 'yaml-mcp_servers') {
         const config = readYamlConfig(configPath);
         const servers = config.mcp_servers;
         if (servers && typeof servers === 'object' && !Array.isArray(servers)) {
@@ -2576,8 +2683,13 @@ function extractNpmVersion(args) {
 /**
  * Strip JSON comments for JSONC parsing.
  * Only removes comments outside of strings.
+ *
+ * Exported because the MCP writer needs the SAME parser the reader uses: a
+ * naive `//`-to-end-of-line regex eats the `//` inside
+ * `"$schema": "https://opencode.ai/config.json"`, which every opencode-generated
+ * config carries.
  */
-function stripJsonComments(content) {
+export function stripJsonComments(content) {
     let result = '';
     let inString = false;
     let escape = false;
@@ -2723,142 +2835,33 @@ function parseMcpFromOpenCodeConfig(configPath) {
 }
 /**
  * Get user-scoped MCP config path for an agent.
+ *
+ * All three MCP path resolvers read `MCP_TARGETS`, so the file the writer
+ * targets, the file the parser reads, and the file the staleness detector
+ * watches cannot drift apart. An agent with no MCP target (the hard-deprecated
+ * `gemini`) keeps the historical settings.json default so old configs still
+ * parse.
  */
 export function getUserMcpConfigPath(agentId) {
-    const agent = AGENTS[agentId];
-    switch (agentId) {
-        case 'claude':
-            // Claude user-scoped MCPs are in ~/.claude.json (global user config)
-            return path.join(HOME, '.claude.json');
-        case 'codex':
-            // Codex uses TOML config
-            return path.join(agent.configDir, 'config.toml');
-        case 'opencode':
-            // OpenCode loads ~/.config/opencode/opencode.jsonc (not ~/.opencode/)
-            return path.join(HOME, '.config', 'opencode', 'opencode.jsonc');
-        case 'cursor':
-            // Cursor uses mcp.json
-            return path.join(agent.configDir, 'mcp.json');
-        case 'openclaw':
-            // OpenClaw uses openclaw.json
-            return path.join(agent.configDir, 'openclaw.json');
-        case 'copilot':
-            // GitHub Copilot CLI uses mcp-config.json (matches versioned + project paths)
-            return path.join(agent.configDir, 'mcp-config.json');
-        case 'antigravity':
-            // agy uses mcp_config.json inside its nested config dir (~/.gemini/antigravity-cli/)
-            return path.join(agent.configDir, 'mcp_config.json');
-        case 'grok':
-            // grok mcp.json — exact field schema verified at first install
-            return path.join(agent.configDir, 'mcp.json');
-        case 'droid':
-            // Factory AI Droid stores MCPs in ~/.factory/mcp.json
-            return path.join(agent.configDir, 'mcp.json');
-        case 'hermes':
-            return path.join(agent.configDir, 'config.yaml');
-        case 'pi':
-            // omp reads user-scope MCP from ~/.omp/agent/.mcp.json (Claude schema).
-            return path.join(agent.configDir, '.mcp.json');
-        case 'muse':
-            // Muse Code: MCP lives in ~/.config/muse/settings.json under mcp_servers.
-            return path.join(agent.configDir, 'settings.json');
-        case 'warp':
-            // Oz reads user-scope MCP from ~/.warp/.mcp.json (Claude schema).
-            return path.join(agent.configDir, '.mcp.json');
-        default:
-            // Gemini and others use settings.json
-            return path.join(agent.configDir, 'settings.json');
-    }
+    return getMcpConfigPathForHome(agentId, HOME);
 }
 /**
  * Get MCP config path for a specific HOME directory (used for version-managed agents).
  */
 export function getMcpConfigPathForHome(agentId, home) {
-    switch (agentId) {
-        case 'claude':
-            return path.join(home, '.claude.json');
-        case 'codex':
-            return path.join(home, '.codex', 'config.toml');
-        case 'opencode':
-            return path.join(home, '.config', 'opencode', 'opencode.jsonc');
-        case 'cursor':
-            return path.join(home, '.cursor', 'mcp.json');
-        case 'openclaw':
-            return path.join(home, '.openclaw', 'openclaw.json');
-        case 'copilot':
-            return path.join(home, '.copilot', 'mcp-config.json');
-        case 'amp':
-            return path.join(home, '.config', 'amp', 'settings.json');
-        case 'kiro':
-            return path.join(home, '.kiro', 'settings', 'mcp.json');
-        case 'goose':
-            return path.join(home, '.config', 'goose', 'config.yaml');
-        case 'antigravity':
-            return path.join(home, '.gemini', 'antigravity-cli', 'mcp_config.json');
-        case 'grok':
-            return path.join(home, '.grok', 'config.toml');
-        case 'droid':
-            return path.join(home, '.factory', 'mcp.json');
-        case 'hermes':
-            return path.join(home, '.hermes', 'config.yaml');
-        case 'pi':
-            return path.join(home, '.omp', 'agent', '.mcp.json');
-        case 'muse':
-            return path.join(home, '.config', 'muse', 'settings.json');
-        case 'warp':
-            return path.join(home, '.warp', '.mcp.json');
-        default:
-            return path.join(home, agentConfigDirName(agentId), 'settings.json');
-    }
+    const target = MCP_TARGETS[agentId];
+    if (target)
+        return target.home(home);
+    return path.join(home, agentConfigDirName(agentId), 'settings.json');
 }
 /**
  * Get project-scoped MCP config path for an agent.
  */
 export function getProjectMcpConfigPath(agentId, cwd = process.cwd()) {
-    switch (agentId) {
-        case 'claude':
-            // Claude uses .mcp.json at project root for project-scoped MCPs
-            return path.join(cwd, '.mcp.json');
-        case 'codex':
-            return path.join(cwd, `.${agentId}`, 'config.toml');
-        case 'opencode':
-            // Project config is opencode.jsonc at project root (not .opencode/)
-            return path.join(cwd, 'opencode.jsonc');
-        case 'cursor':
-            return path.join(cwd, `.${agentId}`, 'mcp.json');
-        case 'openclaw':
-            return path.join(cwd, `.${agentId}`, 'openclaw.json');
-        case 'gemini':
-            return path.join(cwd, `.${agentId}`, 'settings.json');
-        case 'copilot':
-            return path.join(cwd, '.copilot', 'mcp-config.json');
-        case 'amp':
-            return path.join(cwd, '.amp', 'settings.json');
-        case 'kiro':
-            return path.join(cwd, '.kiro', 'settings', 'mcp.json');
-        case 'goose':
-            return path.join(cwd, '.goose', 'config.yaml');
-        case 'antigravity':
-            return path.join(cwd, '.gemini', 'antigravity-cli', 'mcp_config.json');
-        case 'grok':
-            return path.join(cwd, '.grok', 'config.toml');
-        case 'droid':
-            return path.join(cwd, '.factory', 'mcp.json');
-        case 'hermes':
-            return path.join(cwd, '.hermes', 'config.yaml');
-        case 'pi':
-            // omp reads project MCP from <root>/.mcp.json (Claude-compatible).
-            return path.join(cwd, '.mcp.json');
-        case 'muse':
-            // Muse project MCP rides the same settings schema under .muse/settings.json
-            // when present; otherwise fall back to the user settings path.
-            return path.join(cwd, '.muse', 'settings.json');
-        case 'warp':
-            // Oz reads project MCP from <root>/.warp/.mcp.json (Claude schema).
-            return path.join(cwd, '.warp', '.mcp.json');
-        default:
-            return path.join(cwd, `.${agentId}`, 'settings.json');
-    }
+    const target = MCP_TARGETS[agentId];
+    if (target)
+        return target.project(cwd);
+    return path.join(cwd, `.${agentId}`, 'settings.json');
 }
 /**
  * Parse MCP servers from OpenClaw's JSON config.
@@ -2902,16 +2905,22 @@ function parseMcpFromOpenClawConfig(configPath) {
  * Parse MCP config based on agent type.
  */
 export function parseMcpConfig(agentId, configPath) {
-    switch (agentId) {
-        case 'codex':
+    // Dispatch on the registry's declared format, not the agent id, so the parser
+    // can never disagree with the writer about a file's serialization -- grok's
+    // TOML config was previously read as JSON and always came back empty.
+    switch (MCP_TARGETS[agentId]?.format) {
+        case 'toml':
             return parseMcpFromTomlConfig(configPath);
-        case 'opencode':
+        case 'opencode-jsonc':
             return parseMcpFromOpenCodeConfig(configPath);
-        case 'openclaw':
+        case 'openclaw-json':
             return parseMcpFromOpenClawConfig(configPath);
-        case 'hermes':
+        case 'yaml':
             return parseMcpFromYamlConfig(configPath);
         default:
+            // claude-json / antigravity-json / muse-json all live in a JSON object;
+            // parseMcpFromJsonConfig accepts mcpServers | mcp_servers | mcp. Agents
+            // with no declared format fall here too, matching prior behavior.
             return parseMcpFromJsonConfig(configPath);
     }
 }
@@ -3035,6 +3044,29 @@ export function resolveAgentName(input) {
 export function isAgentName(input) {
     return resolveAgentName(input) !== null;
 }
+/**
+ * Split a CLI-provided `<agent>[@<version>]` spec into its bare agent id and
+ * optional exact version token, the same way `agents run` does
+ * (commands/exec.ts parses its positional with a plain `split('@')`) — NOT the
+ * agent-spec qualifier engine (`@latest`/`@all`), which enumerates installed
+ * versions for read/diagnostic commands, not a single launch target. Returns an
+ * error message rather than throwing so callers decide exit-vs-continue.
+ */
+export function parseAgentVersionSpec(raw) {
+    const parts = raw.split('@');
+    if (parts.length > 2) {
+        return { error: `Invalid agent spec '${raw}': at most one '@version' is allowed` };
+    }
+    const [rawAgent, rawVersion] = parts;
+    const agent = resolveAgentName(rawAgent);
+    if (!agent) {
+        return { error: `Unknown agent, profile, or workflow: ${rawAgent}. See \`agents list\` for the installed harnesses.` };
+    }
+    if (rawVersion !== undefined && (rawVersion === '' || !VERSION_RE.test(rawVersion))) {
+        return { error: `Invalid version '${rawVersion}' in '${raw}'` };
+    }
+    return { agent, ...(rawVersion ? { version: rawVersion } : {}) };
+}
 /**
  * Build the deprecation notice lines for an agent, or null if it isn't
  * deprecated. Split from the printer so tests can assert the content without