@phnx-labs/agents-cli 1.20.0 → 1.20.4

package/dist/commands/secrets.js

@@ -8,10 +8,12 @@
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { bundleExists, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
-import { deleteKeychainToken, getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
+import { deleteKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { registerSecretsSyncCommands } from './secrets-sync.js';
+import { registerSecretsMigrateAclCommand } from './secrets-migrate.js';
 /** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
 async function promptForSecret(message) {
     if (!isInteractiveTerminal()) {
@@ -178,7 +180,6 @@ function humanAge(iso) {
 function renderBundleRow(b) {
     const entries = describeBundle(b);
     const keys = entries.length;
-    const sync = b.icloud_sync ? chalk.cyan('icloud') : '';
     const expiringCount = countExpiringSoon(b.meta);
     const expiring = expiringCount > 0 ? chalk.yellow(String(expiringCount)) : chalk.gray('-');
     // Timestamp distinction:
@@ -194,12 +195,11 @@ function renderBundleRow(b) {
         : (b.created_at ? chalk.gray('never') : chalk.gray('?'));
     const head = `${chalk.cyan(b.name.padEnd(20))} ` +
         `${String(keys).padEnd(5)} ` +
-        `${padVisible(sync, 6)} ` +
         `${padVisible(expiring, 9)} ` +
         `${padVisible(created, 9)} ` +
         `${padVisible(updated, 9)} ` +
         `${padVisible(used, 7)}`;
-    return b.description ? `${head} ${chalk.gray(b.description)}` : head.trimEnd();
+    return b.description ? `${head} ${chalk.gray(safePrint(b.description))}` : head.trimEnd();
 }
 /** Colorize a variable source kind (literal, keychain, env, file, exec). */
 function kindLabel(kind) {
@@ -220,6 +220,17 @@ function redact(value, reveal) {
         return '';
     return '*'.repeat(Math.min(value.length, 8));
 }
+/**
+ * Strip ASCII / C1 control bytes from a string before printing it to the
+ * terminal. Bundle descriptions, notes, and remote-supplied names can carry
+ * arbitrary text and a malicious value containing ANSI escape sequences (e.g.
+ * OSC 52 clipboard set, screen-clear, cursor moves) would otherwise be
+ * interpreted by the user's terminal. Allow tab and newline so multi-line
+ * notes still render; strip everything else in the C0/C1 ranges plus DEL.
+ */
+function safePrint(s) {
+    return s.replace(/[\x00-\x08\x0B-\x1F\x7F-\x9F]/g, '');
+}
 /**
  * Build a VarMeta patch from CLI flags. Validates each provided field. Returns
  * undefined if no meta flag was passed (so callers know to skip meta updates).
@@ -286,7 +297,7 @@ function renderMetaLine(meta, reveal) {
         parts.push(colored);
     }
     if (meta.note) {
-        let note = meta.note;
+        let note = safePrint(meta.note);
         if (!reveal && note.length > 80) {
             note = note.slice(0, 79) + '\u2026';
         }
@@ -314,7 +325,7 @@ function countExpiringSoon(meta) {
 export function registerSecretsCommands(program) {
     const cmd = program
         .command('secrets')
-        .description('Named bundles of env variables backed by macOS Keychain (iCloud-synced by default). Inject into agents via `agents run --secrets <name>`.');
+        .description('Named bundles of env variables backed by macOS Keychain (device-local, biometry-gated). Inject into agents via `agents run --secrets <name>`.');
     setHelpSections(cmd, {
         examples: `
       # Create a bundle
@@ -340,23 +351,22 @@ export function registerSecretsCommands(program) {
     `,
         notes: `
       Bundles are containers; secrets are the variables inside them. Keychain values
-      never touch disk in plaintext.
-
-      iCloud sync: new bundles use the iCloud-synced keychain by default so they
-      appear on other Macs (same iCloud account, iCloud Keychain enabled). Pass
-      --no-icloud-sync at create time to keep values device-local instead.
+      never touch disk in plaintext. Every item is device-local and gated by Touch ID
+      or device passcode; cross-machine sync is handled by 'agents secrets push/pull'.
 
       See also:
         agents secrets rotate <bundle> <key>           rotate value, preserve metadata
         agents secrets import <bundle> --from .env     bulk import from .env
         agents secrets import <bundle> --from-1password --vault <name>
         agents secrets generate [length]               generate a random password / PIN / hex
+        agents secrets migrate-acl                     upgrade legacy items to the biometry ACL
     `,
     });
     registerCommandGroups(cmd, [
         { title: 'Bundle commands', names: ['list', 'view', 'create', 'rename', 'describe', 'delete'] },
         { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
-        { title: 'Utilities', names: ['exec', 'generate'] },
+        { title: 'Sync commands', names: ['push', 'pull', 'remote-list'] },
+        { title: 'Utilities', names: ['exec', 'generate', 'migrate-acl'] },
     ]);
     cmd
         .command('list')
@@ -369,7 +379,7 @@ export function registerSecretsCommands(program) {
             console.log(chalk.gray('Try: agents secrets create <name>'));
             return;
         }
-        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'SYNC'.padEnd(6)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
+        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
         for (const b of bundles) {
             console.log(renderBundleRow(b));
         }
@@ -387,11 +397,9 @@ export function registerSecretsCommands(program) {
             const entries = describeBundle(bundle);
             console.log(chalk.bold(bundle.name));
             if (bundle.description)
-                console.log(chalk.gray(bundle.description));
+                console.log(chalk.gray(safePrint(bundle.description)));
             if (bundle.allow_exec)
                 console.log(chalk.yellow('allow_exec: true'));
-            if (bundle.icloud_sync)
-                console.log(chalk.cyan('icloud_sync: true'));
             if (bundle.created_at)
                 console.log(chalk.gray(`created_at: ${bundle.created_at} (${humanAge(bundle.created_at)})`));
             if (bundle.updated_at)
@@ -408,19 +416,30 @@ export function registerSecretsCommands(program) {
                 console.error(chalk.red('--reveal in a non-TTY requires --plaintext.'));
                 process.exit(1);
             }
+            // Batch every keychain read into one helper call so --reveal pops
+            // Touch ID once for the whole bundle instead of once per key.
+            const revealedValues = new Map();
+            if (reveal) {
+                const items = entries
+                    .filter((e) => e.kind === 'keychain')
+                    .map((e) => secretsKeychainItem(bundle.name, e.detail));
+                try {
+                    const fetched = getKeychainTokens(items);
+                    for (const [item, value] of fetched)
+                        revealedValues.set(item, value);
+                }
+                catch {
+                    // Fall through to masked output on cancellation / batch failure.
+                }
+            }
             for (const e of entries) {
                 if (e.kind === 'keychain') {
                     const item = secretsKeychainItem(bundle.name, e.detail);
-                    const stored = hasKeychainToken(item, bundle.icloud_sync);
+                    const stored = hasKeychainToken(item);
                     const marker = stored ? chalk.green('stored') : chalk.red('missing');
                     let valueCol = `[keychain:${e.detail}] ${marker}`;
-                    if (reveal && stored) {
-                        try {
-                            valueCol = redact(getKeychainToken(item, bundle.icloud_sync), true);
-                        }
-                        catch {
-                            // fall through to masked
-                        }
+                    if (reveal && revealedValues.has(item)) {
+                        valueCol = redact(revealedValues.get(item), true);
                     }
                     console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${valueCol}`);
                 }
@@ -429,7 +448,7 @@ export function registerSecretsCommands(program) {
                     const literalValue = typeof raw === 'string'
                         ? raw
                         : (raw && typeof raw === 'object' && 'value' in raw ? raw.value : '');
-                    console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${literalValue}`);
+                    console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${redact(literalValue, reveal)}`);
                 }
                 else {
                     console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${e.detail}`);
@@ -451,7 +470,6 @@ export function registerSecretsCommands(program) {
         .description('Create an empty bundle')
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
-        .option('--no-icloud-sync', 'Store keychain values device-local instead of syncing them via iCloud Keychain')
         .option('--force', 'Overwrite an existing bundle')
         .action(async (name, opts) => {
         try {
@@ -465,7 +483,6 @@ export function registerSecretsCommands(program) {
                 name: resolvedName,
                 description: opts.description,
                 allow_exec: opts.allowExec,
-                icloud_sync: opts.icloudSync !== false,
                 vars: {},
             };
             writeBundle(bundle);
@@ -600,12 +617,11 @@ export function registerSecretsCommands(program) {
                 secretValue = await promptForSecret(`Enter value for ${resolvedBundleName}.${resolvedKey}`);
             }
             const item = secretsKeychainItem(resolvedBundleName, resolvedKey);
-            setKeychainToken(item, secretValue, bundle.icloud_sync);
+            setKeychainToken(item, secretValue);
             bundle.vars[resolvedKey] = keychainRef(resolvedKey);
             applyMeta();
             writeBundle(bundle);
-            const where = bundle.icloud_sync ? 'iCloud Keychain' : 'keychain';
-            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in ${where} (${item}).`));
+            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in keychain (${item}).`));
         }
         catch (err) {
             if (isPromptCancelled(err))
@@ -665,8 +681,7 @@ Examples:
                 clearMeta: opts.clearMeta,
                 meta: metaPatch,
             });
-            const where = bundle.icloud_sync ? 'iCloud Keychain' : 'keychain';
-            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} rotated in ${where}.`));
+            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} rotated in keychain.`));
         }
         catch (err) {
             if (isPromptCancelled(err))
@@ -679,6 +694,7 @@ Examples:
         .command('remove [bundle] [key]')
         .description('Remove a key from the bundle. Purges the keychain item if the ref was keychain:. Use --keep-secret to retain it.')
         .option('--keep-secret', 'Leave the keychain item in place after removing the ref from the bundle')
+        .option('-y, --yes', 'Skip the confirmation prompt when purging a keychain item')
         .action(async (bundleName, key, opts) => {
         try {
             const resolvedBundleName = bundleName ?? (await pickBundleName('remove from'));
@@ -689,11 +705,28 @@ Examples:
                 process.exit(1);
             }
             const raw = bundle.vars[resolvedKey];
+            const willPurge = !opts.keepSecret && typeof raw === 'string' && raw.startsWith('keychain:');
+            if (willPurge && !opts.yes) {
+                if (!isInteractiveTerminal()) {
+                    console.error(chalk.red(`Refusing to purge keychain item for ${resolvedBundleName}.${resolvedKey} non-interactively. ` +
+                        `Pass --yes to confirm or --keep-secret to retain the keychain entry.`));
+                    process.exit(1);
+                }
+                const { confirm } = await import('@inquirer/prompts');
+                const ok = await confirm({
+                    message: `Purge keychain item for ${resolvedBundleName}.${resolvedKey}? (use --keep-secret to retain)`,
+                    default: false,
+                });
+                if (!ok) {
+                    console.log(chalk.gray('Aborted. Bundle metadata unchanged.'));
+                    return;
+                }
+            }
             delete bundle.vars[resolvedKey];
             writeBundle(bundle);
-            if (!opts.keepSecret && typeof raw === 'string' && raw.startsWith('keychain:')) {
+            if (willPurge) {
                 const item = secretsKeychainItem(resolvedBundleName, raw.slice('keychain:'.length));
-                const removed = deleteKeychainToken(item, bundle.icloud_sync);
+                const removed = deleteKeychainToken(item);
                 if (removed) {
                     console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey} and purged keychain item.`));
                     return;
@@ -738,7 +771,7 @@ Examples:
             }
             if (!opts.keepSecrets) {
                 for (const { item } of keychainItemsForBundle(bundle)) {
-                    deleteKeychainToken(item, bundle.icloud_sync);
+                    deleteKeychainToken(item);
                 }
             }
             const existed = deleteBundle(resolvedName);
@@ -824,7 +857,7 @@ Examples:
                     }
                     else {
                         const item = secretsKeychainItem(resolvedBundleName, envKey);
-                        setKeychainToken(item, value, bundle.icloud_sync);
+                        setKeychainToken(item, value);
                         bundle.vars[envKey] = keychainRef(envKey);
                     }
                     added++;
@@ -848,7 +881,7 @@ Examples:
                     }
                     else {
                         const item = secretsKeychainItem(resolvedBundleName, key);
-                        setKeychainToken(item, value, bundle.icloud_sync);
+                        setKeychainToken(item, value);
                         bundle.vars[key] = keychainRef(key);
                     }
                     added++;
@@ -908,8 +941,8 @@ Examples:
                 console.log(chalk.green(`Exported to 1Password vault '${vault}': ${parts.join(', ')}.`));
                 return;
             }
-            if (isInteractiveTerminal() && !opts.plaintext) {
-                console.error(chalk.red('export to a TTY requires --plaintext (prevents shoulder-surfing).'));
+            if (!opts.plaintext) {
+                console.error(chalk.red('export prints secrets in the clear and requires --plaintext (works for TTY and pipes alike).'));
                 process.exit(1);
             }
             const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `export to shell` });
@@ -1033,4 +1066,6 @@ Examples:
             console.log(password);
         }
     });
+    registerSecretsSyncCommands(cmd);
+    registerSecretsMigrateAclCommand(cmd);
 }

package/dist/commands/skills.js

@@ -7,9 +7,9 @@ import { select, checkbox } from '@inquirer/prompts';
 import { AGENTS, SKILLS_CAPABLE_AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.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, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, promptRemovalTargets, } 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) {
@@ -202,11 +202,24 @@ Examples:
                         spinner.succeed('Using local path');
                     }
                 }
-                console.log(chalk.bold(`\nFound ${discoveredSkills.length} skill(s):`));
                 if (discoveredSkills.length === 0) {
                     console.log(chalk.yellow('No skills found (looking for SKILL.md files)'));
                     return;
                 }
+                // Filter by --names if provided. Mirrors the no-source path's behavior
+                // so users can pluck specific skills from a multi-skill repo.
+                const requestedNames = parseCommaSeparatedList(options.names);
+                if (requestedNames.length > 0) {
+                    const discoveredNames = new Set(discoveredSkills.map((s) => s.name));
+                    const missing = requestedNames.filter((n) => !discoveredNames.has(n));
+                    if (missing.length > 0) {
+                        console.log(chalk.red(`\nSkill(s) not found in source: ${missing.join(', ')}`));
+                        console.log(chalk.gray(`Available: ${[...discoveredNames].join(', ')}`));
+                        process.exit(1);
+                    }
+                    discoveredSkills = discoveredSkills.filter((s) => requestedNames.includes(s.name));
+                }
+                console.log(chalk.bold(`\nFound ${discoveredSkills.length} skill(s):`));
                 for (const skill of discoveredSkills) {
                     const nameColor = skill.parseError ? chalk.yellow : chalk.cyan;
                     console.log(`\n  ${nameColor(skill.name)}: ${skill.metadata.description || 'no description'}`);
@@ -238,13 +251,17 @@ Examples:
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
-                const result = resolveAgentVersionTargets(options.agents, SKILLS_CAPABLE_AGENTS);
+                const result = await resolveAgentTargetsAutoInstalling(options.agents, SKILLS_CAPABLE_AGENTS, { yes: options.yes });
+                if (!result) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
             }
             else {
                 const result = await promptAgentVersionSelection(SKILLS_CAPABLE_AGENTS, {
-                    skipPrompts: options.yes || !isInteractiveTerminal(),
+                    skipPrompts: options.yes,
                 });
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;

package/dist/commands/subagents.js

@@ -9,13 +9,12 @@ import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
-import { checkbox } from '@inquirer/prompts';
-import { AGENTS, agentLabel } from '../lib/agents.js';
+import { agentLabel } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverSubagentsFromRepo, installSubagentCentrally, listInstalledSubagents, getInstalledSubagent, listSubagentsForAgent, SUBAGENT_CAPABLE_AGENTS, iterSubagentsCapableVersions, removeSubagentFromVersion, } from '../lib/subagents.js';
-import { listInstalledVersions, syncResourcesToVersion, getGlobalDefault, getVersionHomePath, } from '../lib/versions.js';
-import { getSubagentsDir } from '../lib/state.js';
-import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection, requireDestructiveArg, promptRemovalTargets, } from './utils.js';
+import { listInstalledVersions, syncResourcesToVersion, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, } from '../lib/versions.js';
+import { getSubagentsDir, recordVersionResources } from '../lib/state.js';
+import { requireDestructiveArg, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Replace the home directory prefix with ~ for display. */
 function formatPath(p) {
@@ -102,13 +101,20 @@ Examples:
     subagentsCmd
         .command('add <source>')
         .description('Install subagents from a source (GitHub, local path) and sync to agent versions')
-        .option('-a, --agents <agents...>', 'Targets: claude, openclaw (defaults to all subagent-capable agents)')
+        .option('-a, --agents <list>', 'Targets: claude, openclaw, claude@2.1.141, claude@all, all')
+        .option('--names <list>', 'Subagent names from the source (comma-separated)')
         .option('-y, --yes', 'Skip all prompts and confirmations')
         .addHelpText('after', `
 Examples:
   # Install from GitHub
   agents subagents add gh:team/subagents --agents claude,openclaw
 
+  # Pluck specific subagents from a multi-subagent repo
+  agents subagents add gh:team/subagents --names code-reviewer,planner
+
+  # Install across every installed Claude version
+  agents subagents add gh:team/subagents --agents claude@all
+
   # Install from local directory (must contain subagents/*/AGENT.md)
   agents subagents add ~/my-subagent --agents claude
 
@@ -117,9 +123,13 @@ Examples:
 `)
         .action(async (source, options) => {
         const spinner = ora({ text: 'Fetching source...', isSilent: !process.stdout.isTTY }).start();
-        // Clone or use local source
+        // Clone or use local source. Accept any git-like scheme to match the
+        // other <resource> add commands (skills, workflows, commands, hooks).
         let sourcePath;
-        if (source.startsWith('gh:') || source.startsWith('http')) {
+        const isGitRepo = source.startsWith('gh:') || source.startsWith('git:') ||
+            source.startsWith('ssh:') || source.startsWith('https://') ||
+            source.startsWith('http://');
+        if (isGitRepo) {
             try {
                 const cloneResult = await cloneRepo(source);
                 sourcePath = cloneResult.localPath;
@@ -138,12 +148,24 @@ Examples:
         }
         // Discover subagents
         spinner.text = 'Discovering subagents...';
-        const discovered = discoverSubagentsFromRepo(sourcePath);
+        let discovered = discoverSubagentsFromRepo(sourcePath);
         if (discovered.length === 0) {
             spinner.fail('No subagents found in source');
             console.log(chalk.gray(`Expected: subagents/*/AGENT.md`));
             process.exit(1);
         }
+        // --names filter: pluck specific subagents from a multi-subagent source.
+        const requestedNames = parseCommaSeparatedList(options.names);
+        if (requestedNames.length > 0) {
+            const discoveredNames = new Set(discovered.map((s) => s.name));
+            const missing = requestedNames.filter((n) => !discoveredNames.has(n));
+            if (missing.length > 0) {
+                spinner.fail(`Subagent(s) not found in source: ${missing.join(', ')}`);
+                console.log(chalk.gray(`Available: ${[...discoveredNames].join(', ')}`));
+                process.exit(1);
+            }
+            discovered = discovered.filter((s) => requestedNames.includes(s.name));
+        }
         spinner.succeed(`Found ${discovered.length} subagent(s)`);
         // Show what we found
         console.log();
@@ -151,42 +173,29 @@ Examples:
             console.log(`  ${chalk.cyan(sub.name)}: ${chalk.gray(sub.frontmatter.description)}`);
         }
         console.log();
-        // Determine target agents
-        let targetAgents = options.agents || [];
-        if (targetAgents.length === 0 && !options.yes) {
-            // Prompt for target agents
-            const installedAgents = SUBAGENT_CAPABLE_AGENTS.filter(id => {
-                const versions = listInstalledVersions(id);
-                return versions.length > 0;
-            });
-            if (installedAgents.length === 0) {
-                console.log(chalk.yellow('No subagent-capable agents installed'));
-                console.log(chalk.gray('Subagents will be stored centrally and synced when you install claude or openclaw'));
-                targetAgents = [];
-            }
-            else {
-                if (!isInteractiveTerminal()) {
-                    requireInteractiveSelection('Selecting target agents for subagents', [
-                        'agents subagents add <source> --agents claude openclaw',
-                        'agents subagents add <source> --yes',
-                    ]);
-                }
-                try {
-                    targetAgents = await checkbox({
-                        message: 'Install to which agents?',
-                        choices: installedAgents.map(id => ({
-                            name: AGENTS[id].name,
-                            value: id,
-                            checked: true,
-                        })),
-                    });
-                }
-                catch (err) {
-                    if (isPromptCancelled(err))
-                        return;
-                    throw err;
-                }
+        // Determine target agent versions, using the same path skills/workflows use.
+        // Back-compat: commander's old `--agents <agents...>` shape arrives as an array;
+        // join it with commas so resolveAgentVersionTargets can parse it.
+        const agentsArg = Array.isArray(options.agents)
+            ? options.agents.join(',')
+            : options.agents;
+        let selectedAgents;
+        let versionSelections;
+        if (agentsArg) {
+            const result = await resolveAgentTargetsAutoInstalling(agentsArg, SUBAGENT_CAPABLE_AGENTS, { yes: options.yes });
+            if (!result) {
+                console.log(chalk.gray('Cancelled.'));
+                return;
             }
+            selectedAgents = result.selectedAgents;
+            versionSelections = result.versionSelections;
+        }
+        else {
+            const result = await promptAgentVersionSelection(SUBAGENT_CAPABLE_AGENTS, {
+                skipPrompts: options.yes,
+            });
+            selectedAgents = result.selectedAgents;
+            versionSelections = result.versionSelections;
         }
         // Install centrally
         const installSpinner = ora({ text: 'Installing subagents...', isSilent: !process.stdout.isTTY }).start();
@@ -198,16 +207,27 @@ Examples:
             }
         }
         installSpinner.succeed(`Installed ${discovered.length} subagent(s) to ${formatPath(getSubagentsDir())}`);
-        // Sync to target agents
-        if (targetAgents.length > 0) {
+        // Sync to selected versions
+        if (versionSelections.size > 0) {
             const syncSpinner = ora({ text: 'Syncing to agents...', isSilent: !process.stdout.isTTY }).start();
-            for (const agentId of targetAgents) {
-                const versions = listInstalledVersions(agentId);
+            const subagentNames = discovered.map((s) => s.name);
+            let synced = 0;
+            for (const [agentId, versions] of versionSelections) {
                 for (const version of versions) {
                     syncResourcesToVersion(agentId, version);
+                    recordVersionResources(agentId, version, 'subagents', subagentNames);
+                    synced++;
                 }
             }
-            syncSpinner.succeed(`Synced to ${targetAgents.map(id => agentLabel(id)).join(', ')}`);
+            if (synced > 0) {
+                syncSpinner.succeed(`Synced to ${synced} agent version(s) across ${selectedAgents.map((id) => agentLabel(id)).join(', ')}`);
+            }
+            else {
+                syncSpinner.info('No version-managed agents to sync');
+            }
+        }
+        else {
+            console.log(chalk.gray('Stored centrally; no agent versions selected for sync.'));
         }
         console.log();
     });

package/dist/commands/teams.js

@@ -14,6 +14,7 @@ import { buildPreview as buildSessionPreview } from './sessions-picker.js';
 import { parseExecEnv } from '../lib/exec.js';
 import { teamPicker, printTeamTable } from './teams-picker.js';
 import { itemPicker } from '../lib/picker.js';
+import { profileExists, readProfile } from '../lib/profiles.js';
 import { isPromptCancelled, isInteractiveTerminal, requireDestructiveArg, requireInteractiveSelection, } from './utils.js';
 const AGENT_NAMES = {
     claude: 'Claude',
@@ -25,7 +26,8 @@ const AGENT_NAMES = {
     antigravity: 'Antigravity',
 };
 const VALID_AGENTS = Object.keys(AGENT_NAMES);
-const VALID_MODES = ['plan', 'edit', 'full'];
+// 'full' kept as historical alias for 'skip'; normalized to 'skip' downstream.
+const VALID_MODES = ['plan', 'edit', 'auto', 'skip', 'full'];
 const VALID_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'auto'];
 const VALID_CLOUD_PROVIDERS = ['rush', 'codex', 'factory'];
 // Auto-enable JSON mode when piped / not a TTY so AI agent consumers get
@@ -87,14 +89,48 @@ function fullName(type, version) {
     const name = AGENT_NAMES[type];
     return version ? `${name} ${version}` : name;
 }
+/**
+ * Resolve a teammate spec to its execution target.
+ *
+ * Accepts:
+ *  - `claude`            — default version of an installed agent
+ *  - `claude@2.1.112`    — pinned version of an installed agent
+ *  - `<profile-name>`    — runs through `agents run <profile>`, with the
+ *                          profile's host agent used as the underlying
+ *                          AgentType for event parsing and CLI checks.
+ *
+ * `agent` is always the underlying harness so event parsers, CLI-availability
+ * checks, and version pins keep working. `profileName` is set only when the
+ * spec resolved through a profile.
+ */
 function parseTeammate(spec) {
     const [name, version] = spec.split('@');
-    if (!VALID_AGENTS.includes(name)) {
-        die(`Unknown teammate '${name}'. Available: ${VALID_AGENTS.join(', ')}.\n` +
-            `  Use the form 'claude' or 'claude@2.1.112' (see 'agents view' for installed versions).`);
+    if (VALID_AGENTS.includes(name)) {
+        const agent = name;
+        return {
+            agent,
+            version: resolveVersionAlias(agent, version) ?? null,
+            profileName: null,
+        };
+    }
+    // Not a built-in agent id — try resolving as a profile name. A profile
+    // pinning a version is allowed; `profile@<override>` is not (would conflict
+    // with the profile's own host.version).
+    if (!version && profileExists(name)) {
+        try {
+            const profile = readProfile(name);
+            return {
+                agent: profile.host.agent,
+                version: profile.host.version ?? null,
+                profileName: profile.name,
+            };
+        }
+        catch (err) {
+            die(`Profile '${name}' is malformed: ${err.message}`);
+        }
     }
-    const agent = name;
-    return { agent, version: resolveVersionAlias(agent, version) ?? null };
+    die(`Unknown teammate '${spec}'. Available agents: ${VALID_AGENTS.join(', ')}.\n` +
+        `  Use 'claude', 'claude@2.1.112', or the name of a profile from 'agents view'.`);
 }
 function shortId(id) {
     return id.slice(0, 8);
@@ -547,6 +583,8 @@ export function registerTeamsCommands(program) {
       Teammate syntax:
         'claude'           the default Claude version on this machine
         'claude@2.1.112'   a specific installed version (see 'agents view')
+        '<profile>'        a profile from 'agents view' — runs through 'agents
+                           run <profile>' with the profile's host harness
 
       Short aliases:
         teams c  = create    teams a  = add       teams s  = status
@@ -711,7 +749,7 @@ export function registerTeamsCommands(program) {
         .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.')
-        .option('-m, --mode <mode>', `Permissions: plan (read-only) | edit (can write files) | full (write + skip permission prompts)`, 'edit')
+        .option('-m, --mode <mode>', `Permissions: plan (read-only) | edit (can write files) | auto (smart classifier auto-approves safe ops) | skip (bypass all permission prompts). 'full' accepted as alias for skip.`, 'edit')
         .option('-e, --effort <effort>', `Reasoning intensity: ${VALID_EFFORTS.join('|')}`, 'medium')
         .option('--model <model>', 'Override the effort tier and use this specific model (e.g. claude-opus-4-6)')
         .option('--env <key=value>', 'Set an environment variable for this teammate (repeatable for multiple vars)', (val, prev) => [...prev, val], [])
@@ -747,7 +785,7 @@ export function registerTeamsCommands(program) {
                 die(`--cloud rush requires --repo <owner/repo>`);
             }
         }
-        const { agent, version } = parseTeammate(teammate);
+        const { agent, version, profileName } = parseTeammate(teammate);
         if (version && !isVersionInstalled(agent, version)) {
             die(`${AGENT_NAMES[agent]} ${version} isn't installed.\n` +
                 `  Install it:  agents add ${agent}@${version}\n` +
@@ -872,12 +910,12 @@ export function registerTeamsCommands(program) {
             }
         }
         try {
-            const result = await handleSpawn(mgr, team, agent, effectiveTask, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null, taskType, cloudProviderId, cloudSessionId, opts.repo ?? null, opts.branch ?? null, worktreeName, worktreePath);
+            const result = await handleSpawn(mgr, team, agent, effectiveTask, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null, taskType, cloudProviderId, cloudSessionId, opts.repo ?? null, opts.branch ?? null, worktreeName, worktreePath, profileName);
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify(result, null, 2));
                 return;
             }
-            const who = fullName(agent, version);
+            const who = profileName ? `${profileName} (via ${fullName(agent, version)})` : fullName(agent, version);
             const staged = result.status === 'pending';
             const verb = staged ? 'Staged' : 'Welcomed';
             const greeting = result.name