@phnx-labs/agents-cli 1.20.32 → 1.20.33

package/dist/commands/commands.js

@@ -9,9 +9,9 @@ import { cloneRepo } from '../lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommandCentrally, listCentralCommands, listInstalledCommandsWithScope, getCommandInfo, diffVersionCommands, iterCommandsCapableVersions, removeCommandFromVersion, } from '../lib/commands.js';
 import { getCommandsDir } from '../lib/state.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
-import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 /** Register the `agents commands` command tree (list, add, remove, sync, prune, view). */
 export function registerCommandsCommands(program) {
     const commandsCmd = program
@@ -59,7 +59,7 @@ When to use:
                 process.exit(1);
             }
             filterAgent = resolved;
-            filterVersion = resolveVersionAlias(resolved, parts[1]);
+            filterVersion = resolveListFilterOrExit(resolved, parts[1]);
         }
         const rows = buildCommandRows({ filterAgent, filterVersion });
         spinner.stop();

package/dist/commands/computer-actions.js

@@ -485,6 +485,7 @@ export function registerActionCommands(program) {
         .option('--bundle <id>', 'Bundle id (e.g. com.apple.TextEdit)')
         .option('--path <p>', 'Path to the .app bundle')
         .option('--name <s>', 'App name (resolved via /Applications and LaunchServices)')
+        .option('--host <device>', 'Drive a remote Windows device (requires `agents computer start --host <device>` first)')
         .option('--json', 'Emit JSON')
         .action(async (opts) => {
         if (!opts.bundle && !opts.path && !opts.name) {

package/dist/commands/cost.js

@@ -1,11 +1,11 @@
+import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
 import { queryUsageRollup, topSessionsByCost, } from '../lib/session/db.js';
 import { formatUsd, PRICING_VERSION } from '../lib/pricing/index.js';
 import { formatDuration } from '../lib/session/render.js';
 export function registerCostCommand(program) {
-    program
-        .command('cost')
+    addHostOption(program.command('cost'))
         .description('Roll up $ cost and duration across local agent sessions')
         .option('--json', 'Output the rollup as JSON')
         .option('--since <time>', 'Only sessions newer than this (e.g., 7d, 4w, or ISO date)')

package/dist/commands/doctor.js

@@ -1,3 +1,4 @@
+import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import { checkAllClis } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from '../lib/agents.js';
@@ -475,8 +476,7 @@ async function runFix(parsed, opts) {
 }
 // ─── command registration ────────────────────────────────────────────────────
 export function registerDoctorCommand(program) {
-    const doctorCmd = program
-        .command('doctor [target]')
+    const doctorCmd = addHostOption(program.command('doctor [target]'))
         .description('Diagnose CLI availability, sync status, and resource divergence (optionally for a specific agent[@version]).')
         .option('--json', 'Output machine-readable JSON')
         .option('--diff', 'In target mode, include unified diffs for divergent files')

package/dist/commands/exec.js

@@ -136,7 +136,9 @@ export function registerRunCommand(program) {
         .option('--host <name>', 'Offload this run onto a registered agent host over SSH instead of running locally. See `agents hosts`.')
         .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
         .option('--no-follow', 'With --host, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
-        .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.');
+        .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.')
+        .option('--lease [backend]', 'Invent a disposable cloud box for this run and tear it down after (via crabbox). Optional backend selects the cloud (hetzner/aws/do). Unlike --host, no machine is registered.')
+        .option('--keep-box', 'With --lease, keep the box after the run instead of stopping it.');
     // `--on` and `--computer` are hidden aliases of `--host` — same behavior.
     runCmd.addOption(new Option('--on <name>', 'Alias of --host.').hideHelp());
     runCmd.addOption(new Option('--computer <name>', 'Alias of --host.').hideHelp());
@@ -191,6 +193,59 @@ export function registerRunCommand(program) {
         // Use command.args (all positional strings) and strip the declared positional args from the front.
         const declaredArgCount = prompt !== undefined ? 2 : 1;
         const passthroughArgs = command.args.slice(declaredArgCount);
+        // --lease: invent a disposable cloud box for this run (via crabbox), run
+        // the agent there, then tear it down. Unlike --host, nothing is registered.
+        if (options.lease) {
+            if (prompt === undefined) {
+                console.error(chalk.red('A prompt is required for leased runs: agents run <agent> "<task>" --lease'));
+                process.exit(1);
+            }
+            const backend = typeof options.lease === 'string' ? options.lease : undefined;
+            const { detectSignedInRuntimes, pickRuntimes } = await import('../lib/crabbox/runtimes.js');
+            const { leaseAndRun } = await import('../lib/crabbox/lease.js');
+            const { confirm } = await import('@inquirer/prompts');
+            const detected = await detectSignedInRuntimes();
+            const runtimes = await pickRuntimes(detected);
+            if (runtimes.length === 0) {
+                console.error(chalk.yellow('No runtimes selected. Sign into one locally (e.g. run `claude` once) then retry.'));
+                process.exit(1);
+            }
+            // Security gate: copying auth tokens to an ephemeral cloud box is opt-in
+            // per run. Name the runtimes + accounts so the user sees what ships.
+            const names = runtimes
+                .map((id) => {
+                const d = detected.find((x) => x.id === id);
+                return `${d?.label ?? id}${d?.email ? ` (${d.email})` : ''}`;
+            })
+                .join(', ');
+            const ok = await confirm({
+                message: `Copy credentials for ${names} to a disposable cloud box, run there, then destroy it?`,
+                default: false,
+            });
+            if (!ok) {
+                console.error(chalk.yellow('Aborted — no credentials pushed, no box leased.'));
+                process.exit(1);
+            }
+            try {
+                const { exitCode, box, toreDown } = await leaseAndRun({
+                    agent: agentSpec.split('@')[0],
+                    prompt,
+                    mode: options.mode,
+                    model: options.model,
+                    backend,
+                    runtimes,
+                    detected,
+                    secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE,
+                    keep: options.keepBox,
+                });
+                console.error(chalk.gray(toreDown ? `Box ${box.slug} destroyed.` : `Box ${box.slug} kept${box.ip ? ` (${box.ip})` : ''}. Stop it: crabbox stop --id ${box.slug}`));
+                process.exit(exitCode === null ? 1 : exitCode);
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+        }
         // --host/--on/--computer: offload this run onto a registered agent host
         // over SSH instead of running locally. The three flags are aliases.
         const hostGiven = [options.host, options.on, options.computer].filter((v) => !!v);

package/dist/commands/hooks.js

@@ -8,9 +8,9 @@ import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/
 import { supports, capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverHooksFromRepo, installHooksCentrally, listCentralHooks, listInstalledHooksWithScope, getHookInfo, parseHookManifest, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
-import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 /** Register the `agents hooks` command tree (list, add, remove, sync, prune, view). */
 export function registerHooksCommands(program) {
     const hooksCmd = program.command('hooks')
@@ -61,7 +61,7 @@ When to use:
                 console.log(chalk.red(formatAgentError(agentName, [...capableAgents('hooks')])));
                 process.exit(1);
             }
-            requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
+            requestedVersion = resolveListFilterOrExit(agentId, parts[1]) ?? null;
         }
         // Load hook manifest for event display
         const hookManifest = parseHookManifest();

package/dist/commands/inspect.js

@@ -12,6 +12,7 @@
  * AGENT.md / the file itself) so users can click straight to the source.
  */
 import { execSync } from 'child_process';
+import { addHostOption } from '../lib/hosts/option.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -19,6 +20,7 @@ import chalk from 'chalk';
 import * as yaml from 'yaml';
 import { AGENTS, getCliState, resolveAgentName } from '../lib/agents.js';
 import { supports } from '../lib/capabilities.js';
+import { resolveSingleAgentTarget, AgentSpecError } from '../lib/agent-spec/index.js';
 import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
 import { getVersionHomePath } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
@@ -68,8 +70,7 @@ const CAPABILITY_NAMES = [
 ];
 // ─── Command registration ────────────────────────────────────────────────────
 export function registerInspectCommand(program) {
-    const cmd = program
-        .command('inspect <target>')
+    const cmd = addHostOption(program.command('inspect <target>'))
         .description('Inspect one installed agent at one version, or a DotAgents repo (user|system|project|alias|path) — paths, capabilities, resources, drill into any kind.')
         .option('--brief', 'header + capabilities only; skip resources/sessions')
         .option('--json', 'machine-readable JSON output');
@@ -125,25 +126,20 @@ export async function inspectAction(target, options) {
     await renderSummary(agent, version, versionHome, options);
 }
 function parseTarget(target) {
-    const [rawAgent, rawVersion] = target.split('@');
-    const agent = resolveAgentName(rawAgent || '');
-    if (!agent) {
-        console.error(chalk.red(`Unknown agent: ${rawAgent}`));
-        console.error(chalk.gray(`Known agents: ${Object.keys(AGENTS).join(', ')}`));
-        process.exit(1);
+    // Route through the agent-spec engine: bare resolves project pin → global
+    // default → sole installed (the meta-only lookup here previously ignored
+    // project pins); @default/@latest/@oldest/@x.y.z all handled uniformly.
+    try {
+        const { agent, version } = resolveSingleAgentTarget(target);
+        return { agent, version };
     }
-    let version = rawVersion;
-    if (!version || version === 'default') {
-        const meta = readMeta();
-        const def = meta.agents?.[agent];
-        if (!def) {
-            console.error(chalk.red(`No default version set for ${agent}.`));
-            console.error(chalk.gray(`Pass a version: agents inspect ${agent}@<version>`));
+    catch (e) {
+        if (e instanceof AgentSpecError) {
+            console.error(chalk.red(e.message));
             process.exit(1);
         }
-        version = def;
+        throw e;
     }
-    return { agent, version };
 }
 function pickDrillKind(options) {
     const active = [];

package/dist/commands/mcp.js

@@ -7,9 +7,9 @@ import { readManifest, writeManifest, createDefaultManifest } from '../lib/manif
 import { listMcpServerConfigs, discoverMcpConfigsFromRepo, installMcpConfigCentrally, } from '../lib/mcp.js';
 import { cloneRepo } from '../lib/git.js';
 import { getMcpDir } from '../lib/state.js';
-import { getEffectiveHome, getGlobalDefault, listInstalledVersions, getVersionHomePath, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, resolveVersionAlias, syncResourcesToVersion, } from '../lib/versions.js';
+import { getEffectiveHome, getGlobalDefault, listInstalledVersions, getVersionHomePath, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, syncResourcesToVersion, } from '../lib/versions.js';
 import { getUserAgentsDir } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, promptRemovalTargets, parseCommaSeparatedList, ensureAgentVersionsInstalled, resolveAgentTargetsAutoInstalling, resolveInstalledAgentTargetsAutoInstalling, VersionNotInstalledError, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, promptRemovalTargets, parseCommaSeparatedList, ensureAgentVersionsInstalled, resolveAgentTargetsAutoInstalling, resolveInstalledAgentTargetsAutoInstalling, VersionNotInstalledError, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /**
  * Parse a comma-separated --agents string into validated agent IDs and
@@ -159,7 +159,7 @@ When to use:
                 process.exit(1);
             }
             filterAgent = resolved;
-            filterVersion = resolveVersionAlias(resolved, parts[1]);
+            filterVersion = resolveListFilterOrExit(resolved, parts[1]);
         }
         const rows = buildMcpRows({ filterAgent, filterVersion });
         spinner.stop();

package/dist/commands/permissions.js

@@ -8,9 +8,9 @@ import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/
 import { cloneRepo } from '../lib/git.js';
 import { capableAgents, isCapable } from '../lib/capabilities.js';
 import { listInstalledPermissions, discoverPermissionsFromRepo, installPermissionSet, removePermissionSet, applyPermissionsToVersion, readAgentPermissions, exportPermissionsFromPath, getDefaultPermissionSet, computePermissionsDiff, mergePermissionSets, saveDefaultPermissionSet, containsBroadGrants, } from '../lib/permissions.js';
-import { listInstalledVersions, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, resolveVersionAlias, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 export function shouldRefuseBroadPermissions(permissions, allowBroadPermissions) {
     return !allowBroadPermissions && permissions.some((perm) => containsBroadGrants(perm.set) !== null);
 }
@@ -116,7 +116,7 @@ When to use:
                 console.log(chalk.red(formatAgentError(agentName, capableAgents('allowlist'))));
                 process.exit(1);
             }
-            const requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
+            const requestedVersion = resolveListFilterOrExit(agentId, parts[1]) ?? null;
             if (!isCapable(agentId, 'allowlist')) {
                 console.log(chalk.yellow(`${AGENTS[agentId].name} does not support fine-grained permissions`));
                 return;

package/dist/commands/rules.js

@@ -11,7 +11,7 @@ import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResou
 import { recordVersionResources, getActiveRulesPreset, setActiveRulesPreset } from '../lib/state.js';
 import { discoverRulesLayers } from '../lib/rules/compose.js';
 import * as yaml from 'yaml';
-import { isPromptCancelled, formatPath, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, requireDestructiveArg, resolveAgentTargetsAutoInstalling, } from './utils.js';
+import { isPromptCancelled, formatPath, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, requireDestructiveArg, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 /** Register the `agents rules` command tree (list, add, view, remove). */
 export function registerRulesCommands(program) {
     const rulesCmd = program
@@ -73,7 +73,7 @@ Project rules & @-imports:
                 console.log(chalk.red(formatAgentError(agentName)));
                 process.exit(1);
             }
-            requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
+            requestedVersion = resolveListFilterOrExit(agentId, parts[1]) ?? null;
         }
         const renderVersionRules = (agentId, version, isDefault, home) => {
             const agent = AGENTS[agentId];

package/dist/commands/sessions.js

@@ -215,6 +215,23 @@ function signalBadges(s) {
         parts.push(chalk.magenta(`wt:${s.worktree.slug}`));
     return parts.join(' ');
 }
+/**
+ * Compact provenance badge: how to reach the session, not what it's doing.
+ * `ssh` flags a remote host; the tmux pane id is the send-keys target the feed
+ * would type back into. Local, non-tmux sessions add nothing (the common case).
+ */
+function provenanceBadge(p) {
+    if (!p)
+        return '';
+    const parts = [];
+    if (p.transport === 'ssh')
+        parts.push(chalk.red('ssh'));
+    if (p.mux?.kind === 'tmux' && p.mux.pane)
+        parts.push(chalk.green(`tmux ${p.mux.pane}`));
+    else if (p.mux?.kind === 'screen')
+        parts.push(chalk.green('screen'));
+    return parts.join(' ');
+}
 /**
  * Render a single agent-session row inside an already-printed group header.
  * Indent is the leading whitespace (2 spaces for flat groups, 4 inside a
@@ -228,7 +245,7 @@ function printActiveRow(s, indent) {
     const hostCol = chalk.gray(padToWidth(truncateToWidth(s.host ?? '-', 8), 9));
     const statusCol = statusColor(s.status)(padToWidth(truncateToWidth(activityLabel(s), 8), 9));
     const fork = s.pidCount && s.pidCount > 1 ? chalk.dim(`×${s.pidCount} `) : '';
-    const badges = (fork ? fork : '') + signalBadges(s);
+    const badges = (fork ? fork : '') + [signalBadges(s), provenanceBadge(s.provenance)].filter(Boolean).join(' ');
     const desc = buildSessionDescription(s) || '-';
     // Fill the remaining width with the preview so nothing wraps under tmux/SSH.
     const fixed = stringWidth(indent) + 9 + 9 + 9 + 9 + (badges ? stringWidth(badges) + 1 : 0);

package/dist/commands/skills.js

@@ -8,9 +8,9 @@ import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/
 import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverSkillsFromRepo, installSkillCentrally, listInstalledSkills, listInstalledSkillsWithScope, getSkillInfo, getSkillRules, getSkillsDir, countSkillFiles, tryParseSkillMetadata, diffVersionSkills, iterSkillsCapableVersions, removeSkillFromVersion, } from '../lib/skills.js';
-import { getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
+import { getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, promptRemovalTargets, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, promptRemovalTargets, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Register the `agents skills` command tree (list, add, remove, sync, prune, view). */
 export function registerSkillsCommands(program) {
@@ -59,7 +59,7 @@ When to use:
                 process.exit(1);
             }
             filterAgent = resolved;
-            filterVersion = resolveVersionAlias(resolved, parts[1]);
+            filterVersion = resolveListFilterOrExit(resolved, parts[1]);
         }
         const rows = await buildSkillRows({ filterAgent, filterVersion });
         spinner.stop();

package/dist/commands/sync.js

@@ -35,10 +35,10 @@ import { compileRulesForProject } from '../lib/rules/compile.js';
 import { runLaunchSync } from '../lib/project-launch.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { runUmbrellaSync } from '../lib/sync-umbrella.js';
+import { addHostOption } from '../lib/hosts/option.js';
 /** Register the `agents sync` command. */
 export function registerSyncCommand(program) {
-    program
-        .command('sync [agentSpec] [repo]')
+    addHostOption(program.command('sync [agentSpec] [repo]'))
         .summary('Make this machine current, or sync resources into one agent')
         .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", a selector: @latest / @oldest / @pinned (= @default), or @all for every installed version.\n\nAppend a [repo] (or pass --repo) to scope the sync to a single DotAgent repo — system / user / project / <alias>. e.g. "agents sync claude@all system" reconciles only the system repo\'s resources into every installed Claude.\n\nWith NO agent, runs the umbrella verb: fetch remote state (config repos + secrets + sessions) then reconcile it into every installed agent. Scope it with --repos / --secrets / --sessions, --cloud (fetch only), or --local (reconcile only).')
         .option('--agent <agent>', 'Agent identifier (legacy form; prefer the positional spec)')

package/dist/commands/teams.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
 import * as fs from 'fs/promises';
+import { addHostOption } from '../lib/hosts/option.js';
 import * as path from 'path';
 import { AgentManager, checkAllClis, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
@@ -673,8 +674,7 @@ export function registerTeamsCommands(program) {
     `,
     });
     // list
-    teams
-        .command('list [query]')
+    addHostOption(teams.command('list [query]'))
         .alias('ls')
         .description('List your teams, most recent activity first')
         .option('-a, --agent <agent>', 'Filter: only teams with this agent (e.g. claude or claude@2.1.112)')
@@ -785,8 +785,7 @@ export function registerTeamsCommands(program) {
         printTeamTable(rows);
     });
     // create
-    teams
-        .command('create <team>')
+    addHostOption(teams.command('create <team>'))
         .aliases(['c', 'new'])
         .description('Start a new team. No teammates yet; add them with `teams add`.')
         .option('-d, --description <text>', 'One-line summary of what this team is working on')
@@ -825,8 +824,7 @@ export function registerTeamsCommands(program) {
         }
     });
     // add
-    teams
-        .command('add <team> <teammate> <task>')
+    addHostOption(teams.command('add <team> <teammate> <task>'))
         .alias('a')
         .description("Add a teammate to work on a task. Runs in background; returns immediately. Use 'status' to check in.")
         .option('-n, --name <name>', 'Friendly name for this teammate (e.g. alice). Required if using --after. Unique within team.')
@@ -1041,8 +1039,7 @@ export function registerTeamsCommands(program) {
         }
     });
     // status
-    teams
-        .command('status [team]')
+    addHostOption(teams.command('status [team]'))
         .aliases(['s', 'st', 'check'])
         .description("Check in on a team: status, files touched, recent commands, last messages. Pass --verbose for the full per-teammate dump; --since for delta polling.")
         .option('-f, --filter <state>', 'Show only teammates in this state: running, completed, failed, stopped, or all (default: all)', 'all')
@@ -1136,8 +1133,7 @@ export function registerTeamsCommands(program) {
         console.log(chalk.gray(`${running.length} teammate${running.length === 1 ? '' : 's'} running. See 'agents sessions --active' for the full cross-context view.`));
     });
     // start — fire any staged teammates whose --after deps have all completed
-    teams
-        .command('start [team]')
+    addHostOption(teams.command('start [team]'))
         .description('Launch any pending teammates whose --after dependencies are satisfied. Use --watch to keep draining the DAG as teammates finish and as new tasks are added mid-flight.')
         .option('--json', 'Output machine-readable JSON')
         .option('--watch', 'Keep running: poll every --interval seconds, fire new waves, exit when the DAG drains.')
@@ -1190,8 +1186,7 @@ export function registerTeamsCommands(program) {
         }
     });
     // stop
-    teams
-        .command('stop [team] [teammate]')
+    addHostOption(teams.command('stop [team] [teammate]'))
         .description('Stop a running teammate. Can be restarted later. Cleans up worktree if no uncommitted changes.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, ref, opts) => {

package/dist/commands/usage.js

@@ -1,3 +1,4 @@
+import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, resolveAgentName, formatAgentError, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, getVersionHomePath } from '../lib/versions.js';
@@ -5,8 +6,7 @@ import { formatUsageSection, getUsageInfoForIdentity } from '../lib/usage.js';
 /** Agents whose CLI surfaces usage data we can read today. */
 const USAGE_SUPPORTED = new Set(['claude', 'codex']);
 export function registerUsageCommand(program) {
-    program
-        .command('usage [agent]')
+    addHostOption(program.command('usage [agent]'))
         .description('Show rate-limit / quota usage per agent')
         .addHelpText('after', `
 Examples:

package/dist/commands/utils.d.ts

@@ -6,6 +6,14 @@
  */
 import type { AgentId } from '../lib/types.js';
 import { type InstalledAgentTargetResult, type VersionSelectionResult } from '../lib/versions.js';
+/**
+ * Resolve a read/list command's `@version` filter through the agent-spec engine,
+ * exiting cleanly on a bad spec. Drop-in for the old
+ * `resolveVersionAlias(agent, parts[1])`:
+ *   undefined → show all · @default/@pinned → the default version ·
+ *   @latest/@oldest/@x.y.z → concrete.
+ */
+export declare function resolveListFilterOrExit(agent: AgentId, qualifier: string | undefined | null): string | undefined;
 /**
  * Check if an error is from user cancelling a prompt (Ctrl+C)
  */

package/dist/commands/utils.js

@@ -11,6 +11,26 @@ import ora from 'ora';
 import { confirm } from '@inquirer/prompts';
 import { agentLabel, resolveAgentName } from '../lib/agents.js';
 import { installVersion, listInstalledVersions, resolveAgentVersionTargets, resolveInstalledAgentTargets, } from '../lib/versions.js';
+import { resolveListFilter, AgentSpecError } from '../lib/agent-spec/index.js';
+/**
+ * Resolve a read/list command's `@version` filter through the agent-spec engine,
+ * exiting cleanly on a bad spec. Drop-in for the old
+ * `resolveVersionAlias(agent, parts[1])`:
+ *   undefined → show all · @default/@pinned → the default version ·
+ *   @latest/@oldest/@x.y.z → concrete.
+ */
+export function resolveListFilterOrExit(agent, qualifier) {
+    try {
+        return resolveListFilter(agent, qualifier);
+    }
+    catch (e) {
+        if (e instanceof AgentSpecError) {
+            console.error(chalk.red(e.message));
+            process.exit(1);
+        }
+        throw e;
+    }
+}
 /**
  * Check if an error is from user cancelling a prompt (Ctrl+C)
  */

package/dist/commands/versions.js

@@ -1,3 +1,4 @@
+import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -762,8 +763,7 @@ export function registerVersionsCommands(program) {
         }
     });
     // Deprecated: use `agents view` instead
-    program
-        .command('list [agent]')
+    addHostOption(program.command('list [agent]'))
         .description('List installed agent CLI versions')
         .action(async (agentArg) => {
         console.log(chalk.red('Deprecated: "agents list" is now "agents view"\n'));

package/dist/commands/view.js

@@ -1,3 +1,4 @@
+import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -5,9 +6,10 @@ import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, } from '../lib/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, } from '../lib/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
+import { resolveVersionFilter, AgentSpecError } from '../lib/agent-spec/index.js';
 import { listCliStatus } from '../lib/cli-resources.js';
 import { isCapable } from '../lib/capabilities.js';
 import { discoverPlugins, pluginSupportsAgent } from '../lib/plugins.js';
@@ -1298,12 +1300,25 @@ export async function viewAction(agentArg, options) {
         console.log(chalk.red(formatAgentError(agentName)));
         process.exit(1);
     }
-    // Keep 'default'/'pinned' as-is since showAgentResources handles 'default';
-    // resolveVersionAlias returns undefined for both (they're synonyms), which
-    // would otherwise skip the detailed view.
-    const requestedVersion = (parts[1] === 'default' || parts[1] === 'pinned')
-        ? 'default'
-        : (resolveVersionAlias(agentId, parts[1]) ?? null);
+    // Resolve the @version filter through the agent-spec engine:
+    //   bare/@any → null (show all versions), @default/@pinned → 'default'
+    //   (showAgentResources handles it), @latest/@oldest/@x.y.z → concrete.
+    let requestedVersion;
+    try {
+        requestedVersion = resolveVersionFilter(agentId, parts[1]).version;
+    }
+    catch (e) {
+        if (e instanceof AgentSpecError) {
+            if (json) {
+                console.log(JSON.stringify({ error: e.message }));
+            }
+            else {
+                console.log(chalk.red(e.message));
+            }
+            process.exit(1);
+        }
+        throw e;
+    }
     if (prune) {
         if (requestedVersion) {
             console.log(chalk.red('--prune does not take a @version suffix.'));
@@ -1336,8 +1351,7 @@ export async function viewAction(agentArg, options) {
 }
 /** Register the `agents view` command. */
 export function registerViewCommand(program) {
-    program
-        .command('view [agent]')
+    addHostOption(program.command('view [agent]'))
         .description('Show what agent CLIs are installed and which versions you have. Inspect resources when you pass agent@version.')
         .option('--json', 'Emit machine-readable JSON (version list, usage, signed-in status).')
         .option('--prune', 'Remove older installed versions that share an account with a newer installed version. Skips the global default.')

package/dist/commands/workflows.js

@@ -8,9 +8,9 @@ import { resolveAgentName, agentLabel } from '../lib/agents.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverWorkflowsFromRepo, installWorkflowCentrally, removeWorkflow, listInstalledWorkflows, listWorkflowsForAgent, removeWorkflowFromVersion, iterWorkflowsCapableVersions, } from '../lib/workflows.js';
-import { getVersionHomePath, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, } from '../lib/versions.js';
+import { getVersionHomePath, getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, } from '../lib/versions.js';
 import { recordVersionResources, getUserWorkflowsDir } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Register the `agents workflows` command tree (list, view, add, remove). */
 export function registerWorkflowsCommands(program) {
@@ -73,7 +73,7 @@ Examples:
                 process.exit(1);
             }
             filterAgent = resolved;
-            filterVersion = parts[1] ? resolveVersionAlias(resolved, parts[1]) : undefined;
+            filterVersion = resolveListFilterOrExit(resolved, parts[1]);
         }
         const rows = buildWorkflowRows({ filterAgent, filterVersion });
         spinner.stop();

package/dist/index.js

@@ -847,6 +847,18 @@ const requestedCommand = passedArgs.find((arg) => !arg.startsWith('-'));
 // 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');
+// `--host` passthrough: run this invocation on a remote machine over SSH instead
+// of locally. Handled before any local command registration / update check /
+// background sync — a remote run needs none of that. Only the allowlisted
+// read-only + config + teams commands route here; `run`/`sessions` are absent
+// from the table and fall through to their own richer `--host` handling below.
+// `--help`/`--version` stay local (docs must work without a reachable host).
+if (requestedCommand !== undefined && !helpOrVersionRequested) {
+    const { maybeRunOnHost } = await import('./lib/hosts/passthrough.js');
+    if (await maybeRunOnHost(requestedCommand, passedArgs)) {
+        process.exit(process.exitCode ?? 0);
+    }
+}
 // Register only the command(s) this invocation actually uses. Lazy commands
 // (sessions/teams/cloud) are handled after applyGlobalHelpConventions below.
 const isLazyRequest = requestedCommand !== undefined && LAZY_COMMAND_NAMES.has(requestedCommand);

package/dist/lib/agent-spec/index.d.ts

@@ -0,0 +1,18 @@
+import type { AgentId } from '../types.js';
+import type { AgentTarget, ResolveOptions, VersionFilter } from './types.js';
+export * from './types.js';
+export * from './primitives.js';
+/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
+export declare const AGENT_SPEC_HELP: string;
+/** Resolve a spec (single or comma-list) into concrete installed targets. */
+export declare function resolveAgentTargets(spec: string, opts?: ResolveOptions): AgentTarget[];
+/** Resolve a spec that must name exactly one installed version. */
+export declare function resolveSingleAgentTarget(spec: string, opts?: ResolveOptions): {
+    agent: AgentId;
+    version: string;
+    source: import('./types.js').VersionSource;
+};
+/** Resolve a read/list command's version filter (undefined → all, @default → the default, else concrete). */
+export declare function resolveVersionFilter(agent: AgentId, qualifier: string | undefined | null, opts?: ResolveOptions): VersionFilter;
+/** Concrete version filter for list/display commands (undefined → show all, @default → the default version). */
+export declare function resolveListFilter(agent: AgentId, qualifier: string | undefined | null, opts?: ResolveOptions): string | undefined;