@phnx-labs/agents-cli 1.18.5 → 1.19.0

package/dist/commands/exec.js

@@ -8,21 +8,12 @@
 import chalk from 'chalk';
 import { buildExecCommand, parseExecEnv, execAgent, runWithFallback, AGENT_COMMANDS, } from '../lib/exec.js';
 import { profileExists, resolveProfileForRun } from '../lib/profiles.js';
-import { getSystemAgentsDir, getUserAgentsDir } from '../lib/state.js';
-/** Resolve a workflow by name. User repo wins over system repo. Returns the workflow dir or null. */
-function resolveWorkflow(name) {
-    for (const base of [getUserAgentsDir(), getSystemAgentsDir()]) {
-        const dir = path.join(base, 'workflows', name);
-        if (fs.existsSync(path.join(dir, 'WORKFLOW.md')))
-            return dir;
-    }
-    return null;
-}
+import { setHelpSections } from '../lib/help.js';
 import { readBundle, resolveBundleEnv, describeBundle } from '../lib/secrets/bundles.js';
 import { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES, } from '../lib/rotate.js';
 import { getGlobalDefault, getVersionHomePath, resolveVersionAlias } from '../lib/versions.js';
 import { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion } from '../lib/plugins.js';
-import { parseWorkflowFrontmatter } from '../lib/workflows.js';
+import { parseWorkflowFrontmatter, resolveWorkflowRef } from '../lib/workflows.js';
 import * as fs from 'fs';
 import * as path from 'path';
 const VALID_AGENTS = Object.keys(AGENT_COMMANDS);
@@ -39,7 +30,7 @@ function formatRotationBanner(result, verb = 'balanced') {
 }
 /** Register the `agents run <agent> [prompt]` command. */
 export function registerRunCommand(program) {
-    program
+    const runCmd = program
         .command('run <agent> [prompt]')
         .description('Execute an agent. Pass a prompt for headless runs; omit it to launch the agent interactively.')
         .option('-m, --mode <mode>', 'How much the agent can do: plan (read-only), edit (can write files), full (writes + all permissions)', 'plan')
@@ -60,62 +51,50 @@ export function registerRunCommand(program) {
         .option('--fallback <agents>', 'Comma-separated agents to try on rate-limit failure. Each entry accepts an optional @version pin (e.g., codex@0.116.0,gemini). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')
         .option('-b, --balanced', 'Shortcut for --strategy balanced. Ignored when @version is pinned.')
         .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | balanced. Defaults to run.<agent>.strategy, then pinned. (Legacy `rotate` accepted as alias for `balanced`.)')
-        .option('--acp', 'Route through the Agent Client Protocol instead of direct exec. Supported for gemini, claude (via @zed-industries/claude-code-acp adapter). Unified event stream; emits ndjson when --json.')
-        .addHelpText('after', `
-Modes:
-  With a prompt -> headless (pipes output, no TTY, exits when the agent finishes).
-  Without a prompt -> interactive (launches the agent's TUI; stdio is fully inherited).
-
-Run strategy:
-  pinned     Use the workspace/global pinned version from agents.yaml.
-  available  Use the pinned version if it has usage available; otherwise switch
-             to another signed-in version with usage available.
-  balanced   Distribute traffic across healthy accounts using weighted random
-             by remaining capacity — fresher accounts get more, near-exhausted
-             ones get less. Avoids bursting any single account.
-  Configure with run.<agent>.strategy in agents.yaml, or override with
-  --strategy. --balanced is kept as a shortcut for --strategy balanced.
-  Legacy "rotate" is accepted as an alias for "balanced".
-  Ignored when @version is pinned, when a profile is used, or with --fallback.
-
-Examples:
-  # Interactive with the pinned default version
-  agents run claude
-
-  # Interactive, distribute load across healthy accounts
-  agents run claude --strategy balanced
+        .option('--acp', 'Route through the Agent Client Protocol instead of direct exec. Supported for gemini, claude (via @zed-industries/claude-code-acp adapter). Unified event stream; emits ndjson when --json.');
+    setHelpSections(runCmd, {
+        examples: `
+      # Headless, read-only: investigate or summarize without writing files
+      agents run claude "summarize recent git commits" --mode plan
 
-  # Headless, switch away from the pinned version when usage is unavailable
-  agents run claude "summarize recent git commits" --mode plan --strategy available
+      # Headless, can edit: have the agent make changes
+      agents run claude "fix lint errors in src/" --mode edit
 
-  # Pin a specific version (rotation ignored)
-  agents run codex@0.116.0 "fix linting errors in src/" --mode edit
+      # Interactive (TUI) with the pinned default version
+      agents run claude
 
-  # Full autonomy with maximum reasoning for a complex task
-  agents run claude "refactor auth to use JWT" --mode full --effort max
+      # Pipe JSON events to a parser (--quiet drops the preamble)
+      agents run claude "..." --json --quiet | jq
 
-  # Resume a previous conversation to continue work
-  agents run claude "now add rate limiting" --session-id a1b2c3d4 --mode edit
+      # Bounded run — kill the agent after 30 minutes
+      agents run claude "generate sales report for yesterday" --mode plan --timeout 30m
 
-  # Automated cron job: generate daily report with 10-minute timeout
-  agents run claude "generate sales report for yesterday" --mode plan --timeout 10m --json > report.jsonl
+      # Inject a keychain-backed secrets bundle
+      agents run claude "deploy the worker" --secrets prod --mode edit
+    `,
+        notes: `
+      Modes:
+        plan  read-only       edit  can write files       full  writes + all permissions
 
-  # Auto-fallback to codex then gemini if claude hits a rate limit
-  agents run claude "refactor auth module" --mode edit --fallback codex,gemini
+      Run strategy (set via --strategy or run.<agent>.strategy in agents.yaml):
+        pinned     use the workspace/global pinned version (default)
+        available  use pinned if usage available; otherwise switch to another signed-in version
+        balanced   distribute load across healthy accounts by remaining capacity
+        --balanced is shorthand for --strategy balanced. Ignored when @version is pinned, when a profile is used, or with --fallback.
 
-  # Inject a named secrets bundle (keychain-backed)
-  agents run claude "charge a test card" --secrets prod-stripe
+      Fallback: --fallback codex,gemini retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
-  # Pin fallback versions: primary claude@2.0.65, fallback codex@0.116.0 then gemini
-  agents run claude@2.0.65 "deep refactor" --fallback codex@0.116.0,gemini
-`)
-        .action(async (agentSpec, prompt, options) => {
+      Resume: --session-id <id> continues a prior Claude conversation.
+    `,
+    });
+    runCmd.action(async (agentSpec, prompt, options) => {
         // Parse agent@version
         const [rawAgent, rawVersion] = agentSpec.split('@');
         let agent;
         let version = rawVersion || undefined;
         let profileEnv;
         let fromProfile = false;
+        const cwd = options.cwd ?? process.cwd();
         if (isValidAgent(rawAgent)) {
             agent = rawAgent;
         }
@@ -138,13 +117,13 @@ Examples:
                 process.exit(1);
             }
         }
-        else if (resolveWorkflow(rawAgent)) {
-            // Workflow: ~/.agents-system/workflows/<name>/ or ~/.agents/workflows/<name>/
-            // Resolution: user repo wins over system repo (same precedence as all resources).
+        else if (resolveWorkflowRef(rawAgent, cwd)) {
+            // Workflow: explicit directory, project .agents/workflows/<name>, user, system, or extra repo.
+            // Resolution follows resource precedence: direct path, then project > user > system > extras.
             // Structure:
             //   WORKFLOW.md        ← orchestrator instructions fed to claude as system prompt
             //   subagents/*.md     ← flat .md files copied to ~/.claude/agents/ for Agent tool discovery
-            const workflowDir = resolveWorkflow(rawAgent);
+            const workflowDir = resolveWorkflowRef(rawAgent, cwd);
             agent = 'claude';
             const resolvedVersion = resolveVersionAlias('claude', version);
             const versionHome = getVersionHomePath('claude', resolvedVersion ?? getGlobalDefault('claude') ?? '');
@@ -221,7 +200,6 @@ Examples:
             process.exit(1);
         }
         version = resolveVersionAlias(agent, version);
-        const cwd = options.cwd ?? process.cwd();
         const configuredStrategy = getConfiguredRunStrategy(agent, cwd);
         const explicitStrategy = options.strategy ? normalizeRunStrategy(options.strategy) : null;
         if (options.strategy && !explicitStrategy) {

package/dist/commands/factory.js

@@ -4,11 +4,17 @@ import * as path from 'path';
 import { homedir } from 'os';
 import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
 import { insertTask } from '../lib/cloud/store.js';
-const FACTORY_URL = process.env.FACTORY_FLOOR_URL ?? 'https://agents.427yosemite.com';
 function die(msg, code = 1) {
     console.error(chalk.red(msg));
     process.exit(code);
 }
+function requireFactoryUrl() {
+    const url = process.env.FACTORY_FLOOR_URL;
+    if (!url) {
+        die('FACTORY_FLOOR_URL is not set. Point it at your Software Factory endpoint.');
+    }
+    return url;
+}
 function readRushToken() {
     const userYaml = path.join(homedir(), '.rush', 'user.yaml');
     if (!fs.existsSync(userYaml)) {
@@ -22,8 +28,9 @@ function readRushToken() {
     return match[1].replace(/^['"]|['"]$/g, '');
 }
 async function postFactorySubmit(ref) {
+    const factoryUrl = requireFactoryUrl();
     const token = readRushToken();
-    const res = await fetch(`${FACTORY_URL}/factory/submit`, {
+    const res = await fetch(`${factoryUrl}/factory/submit`, {
         method: 'POST',
         headers: {
             'Authorization': `Bearer ${token}`,
@@ -44,8 +51,8 @@ export function registerFactoryCommands(program) {
         .description('Software Factory -- submit Linear tickets to the cloud orchestrator.')
         .addHelpText('after', `
 Examples:
-  agents factory submit RUSH-2451
-  agents factory submit https://linear.app/getrush/issue/RUSH-2451
+  agents factory submit EXAMPLE-2451
+  agents factory submit https://linear.app/example/issue/EXAMPLE-2451
 `);
     factory.hook('preAction', () => {
         if (enabled)
@@ -56,7 +63,7 @@ Examples:
     });
     factory
         .command('submit <linear-ref>')
-        .description('Submit a Linear issue (RUSH-123 or URL) to the Software Factory.')
+        .description('Submit a Linear issue (EXAMPLE-123 or URL) to the Software Factory.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (ref, opts) => {
         const result = await postFactorySubmit(ref);

package/dist/commands/import.js

@@ -28,7 +28,7 @@ import { confirm } from '@inquirer/prompts';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
 import { AGENTS, getCliPath, getCliVersion, agentLabel } from '../lib/agents.js';
 import { getVersionDir } from '../lib/versions.js';
-import { finalizeImport, importAgentBinary, importAgentConfig, resolvePackageDirFromBinary, } from '../lib/import.js';
+import { finalizeImport, importAgentBinary, importAgentConfig, isValidImportVersion, resolvePackageDirFromBinary, } from '../lib/import.js';
 import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
 function isValidAgentId(value) {
     return ALL_AGENT_IDS.includes(value);
@@ -98,6 +98,11 @@ async function runImport(agentArg, opts) {
         console.error(chalk.gray('Pass --version <version> explicitly.'));
         process.exit(1);
     }
+    if (!isValidImportVersion(version)) {
+        console.error(chalk.red(`Invalid version: ${version}`));
+        console.error(chalk.gray('Version must be "latest" or 1-64 letters, numbers, dots, underscores, plus signs, or hyphens.'));
+        process.exit(1);
+    }
     const versionDir = getVersionDir(agentId, version);
     console.log(chalk.bold(`\nImport ${agentLabel(agentId)} v${version}`));
     console.log(`  from: ${chalk.gray(globalPath)}`);

package/dist/commands/mcp.js

@@ -428,7 +428,7 @@ Examples:
     });
     mcpCmd
         .command('register [name]')
-        .description('Apply MCP servers from manifest to agent config files (stdio only for now)')
+        .description('Apply MCP servers from manifest to agent config files')
         .option('-a, --agents <list>', 'Override manifest targets: claude, codex@0.116.0')
         .addHelpText('after', `
 Examples:
@@ -459,19 +459,24 @@ Examples:
             return;
         }
         for (const [mcpName, config] of entries) {
-            if (config.transport === 'http' || !config.command) {
-                console.log(`\n  ${chalk.cyan(mcpName)}: ${chalk.yellow('HTTP transport not yet supported')}`);
+            const transport = config.transport || 'stdio';
+            const commandOrUrl = transport === 'http' ? config.url : config.command;
+            if (!commandOrUrl) {
+                console.log(`\n  ${chalk.cyan(mcpName)}: ${chalk.yellow(`missing ${transport === 'http' ? 'url' : 'command'}`)}`);
                 continue;
             }
             console.log(`\n  ${chalk.cyan(mcpName)}:`);
             const targets = options.agents
                 ? resolveInstalledAgentTargets(options.agents, MCP_CAPABLE_AGENTS)
                 : resolveConfiguredAgentTargets(config.agents, config.agentVersions, MCP_CAPABLE_AGENTS);
-            const results = await registerMcpToTargets(targets, mcpName, config.command, config.scope || 'user', config.transport || 'stdio');
+            const results = await registerMcpToTargets(targets, mcpName, commandOrUrl, config.scope || 'user', transport, { headers: config.headers });
             for (const result of results) {
                 if (result.success) {
                     console.log(`    ${chalk.green('+')} ${formatTargetLabel(result.agentId, result.version)}`);
                 }
+                else if (result.error?.startsWith('skipped:')) {
+                    console.log(`    ${chalk.yellow('-')} ${formatTargetLabel(result.agentId, result.version)}: ${result.error}`);
+                }
                 else {
                     console.log(`    ${chalk.red('x')} ${formatTargetLabel(result.agentId, result.version)}: ${result.error}`);
                 }

package/dist/commands/packages.d.ts

@@ -6,5 +6,8 @@
  * hooks from configured registries or GitHub sources.
  */
 import type { Command } from 'commander';
+import type { McpPackage } from '../lib/types.js';
+import { type McpCommandSpec } from '../lib/mcp.js';
+export declare function buildMcpPackageCommand(pkg: McpPackage): McpCommandSpec;
 /** Register the `agents registry`, `agents search`, and `agents install` commands. */
 export declare function registerPackagesCommands(program: Command): void;

package/dist/commands/packages.js

@@ -7,9 +7,9 @@
  */
 import chalk from 'chalk';
 import ora from 'ora';
-import { AGENTS, ALL_AGENT_IDS, MCP_CAPABLE_AGENTS, getAllCliStates, registerMcpToTargets, agentLabel, } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, MCP_CAPABLE_AGENTS, getAllCliStates, agentLabel, } from '../lib/agents.js';
 import { DEFAULT_REGISTRIES } from '../lib/types.js';
-import { getRegistries, setRegistry, removeRegistry, search as searchRegistries, resolvePackage, } from '../lib/registry.js';
+import { getRegistries, setRegistry, removeRegistry, search as searchRegistries, resolvePackage, validatedNpmSpec, validatedPyPISpec, } from '../lib/registry.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommand, installCommandCentrally, } from '../lib/commands.js';
 import { discoverSkillsFromRepo, installSkill, installSkillCentrally, } from '../lib/skills.js';
@@ -17,6 +17,17 @@ import { discoverHooksFromRepo, installHooks, installHooksCentrally, } from '../
 import { listInstalledVersions, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, syncResourcesToVersion, } from '../lib/versions.js';
 import { isInteractiveTerminal, isPromptCancelled, requireDestructiveArg, requireInteractiveSelection, } from './utils.js';
 import { itemPicker } from '../lib/picker.js';
+import { registerMcpCommandToTargets } from '../lib/mcp.js';
+export function buildMcpPackageCommand(pkg) {
+    const packageName = pkg.name || pkg.registry_name;
+    if (pkg.runtime === 'node') {
+        return { command: 'npx', args: ['-y', validatedNpmSpec(packageName)] };
+    }
+    if (pkg.runtime === 'python') {
+        return { command: 'uvx', args: [validatedPyPISpec(packageName)] };
+    }
+    throw new Error(`Unsupported MCP runtime: ${pkg.runtime}. Supported: node, python.`);
+}
 /**
  * Picker fallback for `registry enable/config [name]`.
  * Returns the picked name, or null if the user cancels. In non-TTY shells,
@@ -378,16 +389,13 @@ When to use:
                         console.log(`  ${arg.name}${req}: ${arg.description || ''}`);
                     }
                 }
-                // Determine command based on runtime
-                let command;
-                if (pkg.runtime === 'node') {
-                    command = `npx -y ${pkg.name || pkg.registry_name}`;
+                let commandSpec;
+                try {
+                    commandSpec = buildMcpPackageCommand(pkg);
                 }
-                else if (pkg.runtime === 'python') {
-                    command = `uvx ${pkg.name || pkg.registry_name}`;
-                }
-                else {
-                    command = pkg.name || pkg.registry_name;
+                catch (err) {
+                    console.log(chalk.red(err.message));
+                    process.exit(1);
                 }
                 const cliStates = await getAllCliStates();
                 const installedAgents = MCP_CAPABLE_AGENTS.filter((id) => cliStates[id]?.installed || listInstalledVersions(id).length > 0);
@@ -399,7 +407,7 @@ When to use:
                     process.exit(1);
                 }
                 console.log(chalk.bold('\nInstalling to agents...'));
-                const results = await registerMcpToTargets(targets, entry.name, command, 'user');
+                const results = await registerMcpCommandToTargets(targets, entry.name, commandSpec, 'user');
                 for (const result of results) {
                     const label = result.version ? `${agentLabel(result.agentId)}@${result.version}` : agentLabel(result.agentId);
                     if (result.success) {

package/dist/commands/permissions.d.ts

@@ -7,5 +7,7 @@
  * semantics and multi-version targeting.
  */
 import type { Command } from 'commander';
+import { discoverPermissionsFromRepo } from '../lib/permissions.js';
+export declare function shouldRefuseBroadPermissions(permissions: ReturnType<typeof discoverPermissionsFromRepo>, allowBroadPermissions: boolean): boolean;
 /** Register the `agents permissions` command tree (list, add, remove, view). */
 export declare function registerPermissionsCommands(program: Command): void;

package/dist/commands/permissions.js

@@ -6,10 +6,13 @@ import * as path from 'path';
 import { confirm, checkbox } from '@inquirer/prompts';
 import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
-import { PERMISSIONS_CAPABLE_AGENTS, listInstalledPermissions, discoverPermissionsFromRepo, installPermissionSet, removePermissionSet, applyPermissionsToVersion, readAgentPermissions, exportPermissionsFromPath, getDefaultPermissionSet, computePermissionsDiff, mergePermissionSets, saveDefaultPermissionSet, } from '../lib/permissions.js';
+import { PERMISSIONS_CAPABLE_AGENTS, listInstalledPermissions, discoverPermissionsFromRepo, installPermissionSet, removePermissionSet, applyPermissionsToVersion, readAgentPermissions, exportPermissionsFromPath, getDefaultPermissionSet, computePermissionsDiff, mergePermissionSets, saveDefaultPermissionSet, containsBroadGrants, } from '../lib/permissions.js';
 import { listInstalledVersions, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, resolveAgentVersionTargets, resolveVersionAlias, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, } from './utils.js';
+export function shouldRefuseBroadPermissions(permissions, allowBroadPermissions) {
+    return !allowBroadPermissions && permissions.some((perm) => containsBroadGrants(perm.set) !== null);
+}
 /** Register the `agents permissions` command tree (list, add, remove, view). */
 export function registerPermissionsCommands(program) {
     const permissionsCmd = program
@@ -201,6 +204,7 @@ When to use:
         .option('--names <list>', 'Permission set names from ~/.agents/permissions/ (comma-separated)')
         .option('--all', 'Apply to all installed versions instead of just defaults')
         .option('--replace', 'Replace managed permission block instead of merging (drops rules no longer in the set)')
+        .option('--allow-broad-permissions', 'Allow permission packs that significantly weaken sandboxing')
         .option('-y, --yes', 'Skip all prompts and confirmations')
         .addHelpText('after', `
 Examples:
@@ -489,6 +493,21 @@ Examples:
                     console.log(`  ${chalk.cyan(perm.name)}${desc}`);
                     console.log(`    ${chalk.gray(`${perm.set.allow.length} allow, ${perm.set.deny?.length || 0} deny rules`)}`);
                 }
+                const broadGrants = permissions
+                    .map((perm) => ({ name: perm.name, grants: containsBroadGrants(perm.set) }))
+                    .filter((entry) => entry.grants !== null);
+                if (broadGrants.length > 0) {
+                    console.error(chalk.yellow('\nWARNING: this permission pack contains broad grants that significantly weaken agent sandboxing:'));
+                    for (const entry of broadGrants) {
+                        for (const rule of entry.grants.broad) {
+                            console.error(`  ${entry.name}: ${rule}: ${entry.grants.reason}`);
+                        }
+                    }
+                    if (shouldRefuseBroadPermissions(permissions, options.allowBroadPermissions === true)) {
+                        console.error(chalk.red('Refusing to install. Re-run with --allow-broad-permissions if you trust this permission pack.'));
+                        process.exit(1);
+                    }
+                }
                 // Confirm installation
                 if (!skipPrompts) {
                     const proceed = await confirm({

package/dist/commands/plugins.d.ts

@@ -6,5 +6,7 @@
  * stored in ~/.agents/plugins/.
  */
 import type { Command } from 'commander';
+import { type PluginCapabilities } from '../lib/plugins.js';
+export declare function shouldRefusePluginInstall(capabilities: PluginCapabilities, allowExecSurfaces: boolean): boolean;
 /** Register the `agents plugins` command tree. */
 export declare function registerPluginsCommands(program: Command): void;

package/dist/commands/plugins.js

@@ -10,7 +10,7 @@ import * as path from 'path';
 import chalk from 'chalk';
 import { input } from '@inquirer/prompts';
 import { PLUGINS_CAPABLE_AGENTS, agentLabel } from '../lib/agents.js';
-import { discoverPlugins, getPlugin, pluginSupportsAgent, removePluginFromVersion, isPluginSynced, installPlugin, updatePlugin, loadUserConfig, saveUserConfig, checkPluginDependencies, } from '../lib/plugins.js';
+import { discoverPlugins, getPlugin, pluginSupportsAgent, removePluginFromVersion, isPluginSynced, installPlugin, updatePlugin, loadUserConfig, saveUserConfig, checkPluginDependencies, hasPluginExecSurfaces, inspectPluginCapabilities, pluginCapabilityLabels, parseInstallSpec, syncPluginToVersion, } from '../lib/plugins.js';
 import { listInstalledVersions, syncResourcesToVersion, getGlobalDefault, getVersionHomePath, } from '../lib/versions.js';
 import { isPromptCancelled, isInteractiveTerminal, requireDestructiveArg, requireInteractiveSelection, promptRemovalTargets, } from './utils.js';
 import { itemPicker } from '../lib/picker.js';
@@ -25,6 +25,9 @@ function formatPath(p) {
     }
     return p;
 }
+export function shouldRefusePluginInstall(capabilities, allowExecSurfaces) {
+    return hasPluginExecSurfaces(capabilities) && !allowExecSurfaces;
+}
 /** Register the `agents plugins` command tree. */
 export function registerPluginsCommands(program) {
     const pluginsCmd = program
@@ -405,6 +408,7 @@ Examples:
     pluginsCmd
         .command('install <spec>')
         .description('Install a plugin from a git URL or local path (format: name@source or source)')
+        .option('--allow-exec-surfaces', 'Allow installing plugins that ship executable surfaces')
         .addHelpText('after', `
 Examples:
   # Install from a git URL
@@ -416,14 +420,16 @@ Examples:
   # Named install from a local path
   agents plugins install rush-toolkit@~/Projects/rush-toolkit
 `)
-        .action(async (spec) => {
+        .action(async (spec, options) => {
         console.log(chalk.gray(`Installing plugin from: ${spec}`));
         let name;
         let root;
+        let capabilities;
         try {
             const result = await installPlugin(spec);
             name = result.name;
             root = result.root;
+            capabilities = result.capabilities;
         }
         catch (err) {
             console.log(chalk.red(`Install failed: ${err.message}`));
@@ -434,6 +440,17 @@ Examples:
             console.log(chalk.red(`Installed but could not load plugin '${name}'`));
             process.exit(1);
         }
+        capabilities = inspectPluginCapabilities(root);
+        if (shouldRefusePluginInstall(capabilities, options.allowExecSurfaces === true)) {
+            const source = parseInstallSpec(spec).source;
+            console.error(chalk.red('Install refused: plugin ships executable surfaces:'));
+            for (const label of pluginCapabilityLabels(capabilities)) {
+                console.error(`  ${label}`);
+            }
+            console.error(`This plugin ships executable surfaces. Re-run with --allow-exec-surfaces if you trust the source: ${source}@HEAD`);
+            fs.rmSync(root, { recursive: true, force: true });
+            process.exit(1);
+        }
         // Check dependencies
         const missingDeps = checkPluginDependencies(plugin.manifest);
         if (missingDeps.length > 0) {
@@ -461,8 +478,10 @@ Examples:
             const defaultVer = getGlobalDefault(agentId);
             const targetVersions = defaultVer ? [defaultVer] : [versions[versions.length - 1]];
             for (const version of targetVersions) {
-                const syncResult = syncResourcesToVersion(agentId, version, { plugins: [name] });
-                if (syncResult.plugins.length > 0) {
+                const didSync = options.allowExecSurfaces === true
+                    ? syncPluginToVersion(plugin, agentId, getVersionHomePath(agentId, version), { allowExecSurfaces: true }).success
+                    : syncResourcesToVersion(agentId, version, { plugins: [name] }).plugins.length > 0;
+                if (didSync) {
                     console.log(chalk.green(`  Synced to ${agentLabel(agentId)}@${version}`));
                     synced++;
                 }

package/dist/commands/profiles.js

@@ -116,7 +116,7 @@ Examples:
 
   # Add MiniMax for SWE-bench style fixes; reuses the same OpenRouter key
   agents profiles add minimax
-  agents run minimax "investigate RUSH-2317 and patch the off-by-one in pagination"
+  agents run minimax "investigate EXAMPLE-2317 and patch the off-by-one in pagination"
 
   # Add DeepSeek for cheap, fast non-reasoning work
   agents profiles add deepseek