@phnx-labs/agents-cli 1.22.22 → 1.22.24

package/dist/commands/setup-secrets.js

@@ -66,7 +66,7 @@ function printBackendNotes(backend) {
         console.log(chalk.gray('backend: keychain — macOS reads may ask for Touch ID or the device password.'));
     }
     else if (backend === 'file') {
-        console.log(chalk.gray('backend: file — set AGENTS_SECRETS_PASSPHRASE for headless encrypted-file reads.'));
+        console.log(chalk.gray('backend: file — encrypted at rest; headless reads need no passphrase by default, via a machine-local key at ~/.agents/.secrets-key/passphrase.'));
     }
     else {
         console.log(chalk.gray('backend: vault — synced ~/.agents/vault.age storage; unlock it with agents login.'));

package/dist/commands/sync.js

@@ -31,6 +31,7 @@
  */
 import * as path from 'path';
 import chalk from 'chalk';
+import { resolveSyncPassphraseFromEnv } from '../lib/secrets/sync-passphrase.js';
 import { agentLabel, resolveAgentName, MANAGED_AGENT_IDS, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
 import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, resolveVersionAlias, listInstalledVersions, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, buildRepoScopedSelection, mergeRepoScopedSelections, listRepoNames, getVersionHomePath, } from '../lib/versions.js';
 import { capableAgents } from '../lib/capabilities.js';
@@ -43,6 +44,10 @@ import { runUmbrellaSync } from '../lib/sync-umbrella.js';
 import { addHostOption } from '../lib/hosts/option.js';
 import { syncRepoGit } from '../lib/git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos } from '../lib/state.js';
+/** Emit one JSON object to stdout for `--json` callers / fleet fan-out. */
+function emitJson(payload) {
+    console.log(JSON.stringify(payload));
+}
 /** Register the `agents sync` command. */
 export function registerSyncCommand(program) {
     addHostOption(program.command('sync [agentSpec] [repo]'))
@@ -57,6 +62,7 @@ export function registerSyncCommand(program) {
         .option('-y, --yes', 'Skip the interactive preview and auto-sync all detected resources', false)
         .option('--force', 'Re-sync even if no changes are detected since the last sync', false)
         .option('--quiet', 'Suppress all output (exit code indicates success)', false)
+        .option('--json', 'Emit machine-readable JSON (also accepted so fleet fan-out via --host all can parse each peer)', false)
         // Umbrella verb (no agent given): make this machine current.
         .option('--repos', 'Umbrella: git-pull ~/.agents + enabled ~/.agents-* extras', false)
         .option('--secrets', 'Umbrella: pull encrypted secret bundles from the remote', false)
@@ -88,22 +94,47 @@ function resolveRepoGitTarget(repo) {
  * tree, else pull --rebase against origin, pushing local commits for user-owned
  * repos. Delegates the git work to `syncRepoGit`.
  */
-async function runRepoGitSync(repo, quiet, outLog, errLog) {
+async function runRepoGitSync(repo, quiet, outLog, errLog, json = false) {
     const target = resolveRepoGitTarget(repo);
     if (!target) {
-        errLog(chalk.red(`The '${repo}' repo isn't independently git-synced.`));
-        errLog(chalk.gray('Syncable repos: system (pull-only), user, and enabled extra-repo aliases.'));
+        if (json) {
+            emitJson({
+                ok: false,
+                mode: 'repo-git',
+                repo,
+                error: `The '${repo}' repo isn't independently git-synced.`,
+            });
+        }
+        else {
+            errLog(chalk.red(`The '${repo}' repo isn't independently git-synced.`));
+            errLog(chalk.gray('Syncable repos: system (pull-only), user, and enabled extra-repo aliases.'));
+        }
         process.exitCode = 1;
         return;
     }
-    if (!quiet)
+    if (!quiet && !json)
         outLog(chalk.bold(`Syncing ${repo} repo…`) + chalk.gray(` (${target.dir})`));
     const result = await syncRepoGit(target.dir, { push: target.push });
     if (!result.success) {
-        errLog(chalk.red(`sync ${repo} failed: ${result.error}`));
+        if (json) {
+            emitJson({ ok: false, mode: 'repo-git', repo, error: result.error ?? 'sync failed' });
+        }
+        else {
+            errLog(chalk.red(`sync ${repo} failed: ${result.error}`));
+        }
         process.exitCode = 1;
         return;
     }
+    if (json) {
+        emitJson({
+            ok: true,
+            mode: 'repo-git',
+            repo,
+            commit: result.commit,
+            pushed: !!result.pushed,
+        });
+        return;
+    }
     if (!quiet) {
         const note = result.pushed ? ' · pushed' : ' · pull-only';
         outLog(chalk.green(`✓ ${repo} → ${result.commit}${note}`));
@@ -201,12 +232,14 @@ async function runInteractiveReconcile(opts, outLog, errLog) {
  * arrives with `agents login`) and runs the fetch+reconcile stages, then prints
  * a one-line summary. Stage failures are non-fatal and surfaced as warnings.
  */
-async function runUmbrella(opts, quiet, outLog, errLog) {
+async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
     // Interactive bare `agents sync` (a TTY, no --yes, no scope flag) drops into
     // the two-checklist picker: which repos to sync from, which agents to sync
-    // into. Any explicit flag or --yes keeps the non-interactive umbrella below.
+    // into. Any explicit flag, --yes, or --json keeps the non-interactive path.
+    // --json is a machine consumer (and the fleet fan-out injects it), so never
+    // open a picker under it.
     const anyExplicitFlag = !!(opts.repos || opts.secrets || opts.cloud || opts.local);
-    if (!quiet && !opts.yes && !anyExplicitFlag && isInteractiveTerminal()) {
+    if (!quiet && !json && !opts.yes && !anyExplicitFlag && isInteractiveTerminal()) {
         await runInteractiveReconcile(opts, outLog, errLog);
         return;
     }
@@ -216,17 +249,36 @@ async function runUmbrella(opts, quiet, outLog, errLog) {
         cloud: opts.cloud,
         local: opts.local,
     };
-    const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE || undefined;
-    if (!quiet)
+    // Same chokepoint as `agents secrets push/pull` — prefers AGENTS_SYNC_PASSPHRASE,
+    // falls back to the deprecated master-key name with a single warning.
+    const passphrase = resolveSyncPassphraseFromEnv().value ?? undefined;
+    // Fleet fan-out only injects --json (not --yes). Treat --json as non-interactive
+    // so refresh({ skipPrompts }) never tries to prompt over SSH.
+    const yes = !!opts.yes || json;
+    if (!quiet && !json)
         outLog(chalk.bold('Syncing this machine…'));
     try {
         const result = await runUmbrellaSync({
             flags,
-            yes: !!opts.yes,
+            yes,
             passphrase,
-            log: (msg) => { if (!quiet)
+            // quiet under --json so refresh() cannot pollute the JSON stdout the fleet parses.
+            quiet: quiet || json,
+            log: (msg) => { if (!quiet && !json)
                 outLog(chalk.gray(`  ${msg}`)); },
         });
+        if (json) {
+            emitJson({
+                ok: true,
+                mode: 'umbrella',
+                plan: result.plan,
+                repos: result.repos,
+                secrets: result.secrets,
+                devices: result.devices,
+                reconciled: result.reconciled,
+            });
+            return;
+        }
         if (!quiet) {
             const parts = [];
             if (result.repos) {
@@ -245,16 +297,30 @@ async function runUmbrella(opts, quiet, outLog, errLog) {
         }
     }
     catch (err) {
-        errLog(chalk.red(`sync failed: ${err.message}`));
+        if (json) {
+            emitJson({ ok: false, mode: 'umbrella', error: err.message });
+        }
+        else {
+            errLog(chalk.red(`sync failed: ${err.message}`));
+        }
         process.exitCode = 1;
     }
 }
 async function runSync(agentSpec, repoArg, opts) {
-    const quiet = !!opts.quiet;
+    const json = !!opts.json;
+    // --json is a machine consumer: suppress human stdout/stderr chatter so the
+    // single JSON object on stdout stays parseable for fleet fan-out.
+    const quiet = !!opts.quiet || json;
     const errLog = (msg) => { if (!quiet)
         console.error(msg); };
     const outLog = (msg) => { if (!quiet)
         console.log(msg); };
+    // Failures under --json still need a structured line on stdout so fleet
+    // fan-out's safeJsonParse gets a real object (not "unknown option").
+    const failJson = (payload) => {
+        if (json)
+            emitJson({ ok: false, ...payload });
+    };
     // ---------- 1. Resolve agent + version ----------
     let agentId;
     let version;
@@ -271,14 +337,21 @@ async function runSync(agentSpec, repoArg, opts) {
     // below, and it precedes agent-spec parsing because repo names like
     // "system"/"user" would otherwise fail parseAgentSpec.
     if (agentSpec && !opts.agent && !repoArg && listRepoNames().includes(agentSpec)) {
-        await runRepoGitSync(agentSpec, quiet, outLog, errLog);
+        await runRepoGitSync(agentSpec, quiet, outLog, errLog, json);
         return;
     }
     if (agentSpec) {
         const parsed = parseAgentSpec(agentSpec);
         if (!parsed) {
-            errLog(chalk.red(`Invalid agent spec '${agentSpec}'.`));
-            errLog(chalk.gray('Examples: claude, claude@2.1.142, claude@latest, claude@oldest, claude@pinned, claude@all'));
+            failJson({
+                mode: 'agent',
+                error: `Invalid agent spec '${agentSpec}'.`,
+                hint: 'Examples: claude, claude@2.1.142, claude@latest, claude@oldest, claude@pinned, claude@all',
+            });
+            if (!json) {
+                errLog(chalk.red(`Invalid agent spec '${agentSpec}'.`));
+                errLog(chalk.gray('Examples: claude, claude@2.1.142, claude@latest, claude@oldest, claude@pinned, claude@all'));
+            }
             process.exitCode = 1;
             return;
         }
@@ -292,8 +365,11 @@ async function runSync(agentSpec, repoArg, opts) {
     if (repoScope !== undefined) {
         const known = listRepoNames();
         if (!known.includes(repoScope)) {
-            errLog(chalk.red(`Unknown repo '${repoScope}'.`));
-            errLog(chalk.gray(`Known repos: ${known.join(', ')}`));
+            failJson({ mode: 'agent', error: `Unknown repo '${repoScope}'.`, known });
+            if (!json) {
+                errLog(chalk.red(`Unknown repo '${repoScope}'.`));
+                errLog(chalk.gray(`Known repos: ${known.join(', ')}`));
+            }
             process.exitCode = 1;
             return;
         }
@@ -301,14 +377,18 @@ async function runSync(agentSpec, repoArg, opts) {
     if (opts.agent) {
         const resolved = resolveAgentName(opts.agent);
         if (!resolved) {
-            errLog(chalk.red(`Unknown agent '${opts.agent}'.`));
+            failJson({ mode: 'agent', error: `Unknown agent '${opts.agent}'.` });
+            if (!json)
+                errLog(chalk.red(`Unknown agent '${opts.agent}'.`));
             process.exitCode = 1;
             return;
         }
         agentId = resolved;
     }
     if (agentId && isAgentHardDeprecated(agentId)) {
-        errLog(chalk.red(hardDeprecationError(agentId)));
+        failJson({ mode: 'agent', error: hardDeprecationError(agentId) });
+        if (!json)
+            errLog(chalk.red(hardDeprecationError(agentId)));
         process.exitCode = 1;
         return;
     }
@@ -320,7 +400,8 @@ async function runSync(agentSpec, repoArg, opts) {
     if (!agentId) {
         // No agent specified → the umbrella verb: make this machine current
         // (fetch repos + secrets + sessions, then reconcile all installed agents).
-        await runUmbrella(opts, quiet, outLog, errLog);
+        // This is the path fleet fan-out (`--host all`) hits with injected --json.
+        await runUmbrella(opts, quiet, outLog, errLog, json);
         return;
     }
     const projectDir = opts.projectDir;
@@ -332,8 +413,11 @@ async function runSync(agentSpec, repoArg, opts) {
     if (selector === 'all') {
         const installed = listInstalledVersions(agentId);
         if (installed.length === 0) {
-            errLog(chalk.red(`No ${agentLabel(agentId)} versions installed.`));
-            errLog(chalk.gray(`Install one: agents add ${agentId}@latest`));
+            failJson({ mode: 'agent-all', agent: agentId, error: `No ${agentLabel(agentId)} versions installed.` });
+            if (!json) {
+                errLog(chalk.red(`No ${agentLabel(agentId)} versions installed.`));
+                errLog(chalk.gray(`Install one: agents add ${agentId}@latest`));
+            }
             process.exitCode = 1;
             return;
         }
@@ -341,17 +425,43 @@ async function runSync(agentSpec, repoArg, opts) {
         if (repoScope) {
             selection = buildRepoScopedSelection(repoScope, cwd);
             if (Object.keys(selection).length === 0) {
-                outLog(chalk.gray(`Nothing from repo '${repoScope}' to sync.`));
+                if (json)
+                    emitJson({ ok: true, mode: 'agent-all', agent: agentId, repo: repoScope, versions: [], note: 'nothing to sync' });
+                else
+                    outLog(chalk.gray(`Nothing from repo '${repoScope}' to sync.`));
                 return;
             }
         }
         const scopeLabel = repoScope ? chalk.gray(` (repo: ${repoScope})`) : '';
-        outLog(chalk.cyan(`Syncing ${installed.length} ${agentLabel(agentId)} version(s)${scopeLabel}.`));
+        if (!json)
+            outLog(chalk.cyan(`Syncing ${installed.length} ${agentLabel(agentId)} version(s)${scopeLabel}.`));
+        const versions = [];
         for (const v of installed) {
             const result = syncResourcesToVersion(agentId, v, selection, { projectDir, cwd, force });
-            if (!quiet)
+            versions.push({ version: v, result });
+            if (!quiet && !json)
                 printSyncDetail(result, agentId, v, cwd);
         }
+        if (json) {
+            emitJson({
+                ok: true,
+                mode: 'agent-all',
+                agent: agentId,
+                repo: repoScope,
+                versions: versions.map(({ version: v, result }) => ({
+                    version: v,
+                    commands: !!result.commands,
+                    skills: !!result.skills,
+                    hooks: !!result.hooks,
+                    memory: result.memory,
+                    mcp: result.mcp,
+                    permissions: !!result.permissions,
+                    subagents: result.subagents,
+                    plugins: result.plugins,
+                    workflows: result.workflows,
+                })),
+            });
+        }
         return;
     }
     // ---------- 2. Resolve version (project pin → global default → sole installed) ----------
@@ -370,15 +480,26 @@ async function runSync(agentSpec, repoArg, opts) {
                 version = installed[0];
             }
             else if (installed.length === 0) {
-                errLog(chalk.red(`No ${agentLabel(agentId)} versions installed.`));
-                errLog(chalk.gray(`Install one: agents add ${agentId}@latest`));
+                failJson({ mode: 'agent', agent: agentId, error: `No ${agentLabel(agentId)} versions installed.` });
+                if (!json) {
+                    errLog(chalk.red(`No ${agentLabel(agentId)} versions installed.`));
+                    errLog(chalk.gray(`Install one: agents add ${agentId}@latest`));
+                }
                 process.exitCode = 1;
                 return;
             }
             else {
-                errLog(chalk.red(`No default ${agentLabel(agentId)} version pinned. Specify one:`));
-                for (const v of installed) {
-                    errLog(chalk.gray(`  agents sync ${agentId}@${v}`));
+                failJson({
+                    mode: 'agent',
+                    agent: agentId,
+                    error: `No default ${agentLabel(agentId)} version pinned.`,
+                    installed,
+                });
+                if (!json) {
+                    errLog(chalk.red(`No default ${agentLabel(agentId)} version pinned. Specify one:`));
+                    for (const v of installed) {
+                        errLog(chalk.gray(`  agents sync ${agentId}@${v}`));
+                    }
                 }
                 process.exitCode = 1;
                 return;
@@ -386,18 +507,27 @@ async function runSync(agentSpec, repoArg, opts) {
         }
     }
     if (!isVersionInstalled(agentId, version)) {
-        errLog(chalk.red(`${agentLabel(agentId)}@${version} is not installed.`));
         const installed = listInstalledVersions(agentId);
-        if (installed.length > 0) {
-            errLog(chalk.gray(`Installed: ${installed.join(', ')}`));
+        failJson({
+            mode: 'agent',
+            agent: agentId,
+            version,
+            error: `${agentLabel(agentId)}@${version} is not installed.`,
+            installed,
+        });
+        if (!json) {
+            errLog(chalk.red(`${agentLabel(agentId)}@${version} is not installed.`));
+            if (installed.length > 0) {
+                errLog(chalk.gray(`Installed: ${installed.join(', ')}`));
+            }
+            errLog(chalk.gray(`Install it: agents add ${agentId}@${version}`));
         }
-        errLog(chalk.gray(`Install it: agents add ${agentId}@${version}`));
         process.exitCode = 1;
         return;
     }
     // ---------- 3. --launch mode bypasses everything below ----------
     if (opts.launch) {
-        runLaunchMode(agentId, version, cwd, quiet);
+        runLaunchMode(agentId, version, cwd, quiet, json);
         return;
     }
     // ---------- 3b. Repo-scoped single-version sync ----------
@@ -406,16 +536,33 @@ async function runSync(agentSpec, repoArg, opts) {
     if (repoScope) {
         const scoped = buildRepoScopedSelection(repoScope, cwd);
         if (Object.keys(scoped).length === 0) {
-            outLog(chalk.gray(`Nothing from repo '${repoScope}' to sync into ${agentLabel(agentId)}@${version}.`));
+            if (json) {
+                emitJson({
+                    ok: true,
+                    mode: 'agent',
+                    agent: agentId,
+                    version,
+                    repo: repoScope,
+                    note: 'nothing to sync',
+                });
+            }
+            else {
+                outLog(chalk.gray(`Nothing from repo '${repoScope}' to sync into ${agentLabel(agentId)}@${version}.`));
+            }
             return;
         }
         const result = syncResourcesToVersion(agentId, version, scoped, { projectDir, cwd, force });
-        if (!quiet)
+        if (json) {
+            emitJson(agentSyncJson(agentId, version, result, repoScope));
+        }
+        else if (!quiet) {
             printSyncDetail(result, agentId, version, cwd);
+        }
         return;
     }
     // ---------- 4. Decide selection (interactive preview vs auto) ----------
-    const yes = !!opts.yes;
+    // --json forces non-interactive (machine consumer / fleet fan-out).
+    const yes = !!opts.yes || json;
     const interactive = !quiet && !yes && isInteractiveTerminal();
     let selection;
     if (interactive) {
@@ -468,6 +615,20 @@ async function runSync(agentSpec, repoArg, opts) {
         const projectRoot = path.dirname(projectDir);
         projectCompile = compileRulesForProject(projectRoot);
     }
+    if (json) {
+        emitJson({
+            ...agentSyncJson(agentId, version, result),
+            projectCompile: projectCompile
+                ? {
+                    compiled: !!projectCompile.compiled,
+                    agentsPath: projectCompile.agentsPath,
+                    symlinks: projectCompile.symlinks,
+                    skippedClobber: projectCompile.skippedClobber,
+                }
+                : null,
+        });
+        return;
+    }
     if (quiet)
         return;
     // ---------- 6. Detailed output ----------
@@ -482,6 +643,26 @@ async function runSync(agentSpec, repoArg, opts) {
         console.log(chalk.yellow(`Skipped (user-authored, not overwritten): ${projectCompile.skippedClobber.join(', ')}`));
     }
 }
+/** Stable `--json` payload for a single agent@version resource sync. */
+function agentSyncJson(agent, version, result, repo) {
+    return {
+        ok: true,
+        mode: 'agent',
+        agent,
+        version,
+        ...(repo !== undefined ? { repo } : {}),
+        commands: !!result.commands,
+        skills: !!result.skills,
+        hooks: !!result.hooks,
+        memory: result.memory,
+        mcp: result.mcp,
+        permissions: !!result.permissions,
+        subagents: result.subagents,
+        plugins: result.plugins,
+        workflows: result.workflows,
+        projectSkipped: result.projectSkipped,
+    };
+}
 function anyResources(r) {
     return r.commands.length + r.skills.length + r.hooks.length + r.memory.length +
         r.mcp.length + r.permissions.length + r.subagents.length +
@@ -533,17 +714,40 @@ function printSyncDetail(result, agent, version, cwd) {
     if (kept)
         console.log(chalk.gray(kept));
 }
-function runLaunchMode(agent, version, cwd, quiet) {
+function runLaunchMode(agent, version, cwd, quiet, json = false) {
     let result;
     try {
         result = runLaunchSync({ agent, version, cwd });
     }
     catch (err) {
-        if (!quiet) {
+        if (json) {
+            emitJson({
+                ok: false,
+                mode: 'launch',
+                agent,
+                version,
+                error: err.message,
+            });
+            process.exitCode = 1;
+        }
+        else if (!quiet) {
             console.error(chalk.yellow(`agents: launch sync skipped (${err.message})`));
         }
         return;
     }
+    if (json) {
+        emitJson({
+            ok: true,
+            mode: 'launch',
+            agent,
+            version,
+            rulesCompiled: !!result.rulesCompiled,
+            workspaceLinks: result.workspaceLinks,
+            marketplaces: result.marketplaces,
+            workspaceSkipped: result.workspaceSkipped,
+        });
+        return;
+    }
     if (quiet)
         return;
     const bits = [];

package/dist/commands/view.js

@@ -578,6 +578,8 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 const runDefaultBits = [];
                 if (runDefaults.mode)
                     runDefaultBits.push(`mode:${runDefaults.mode}`);
+                if (runDefaults.effort)
+                    runDefaultBits.push('effort:' + runDefaults.effort);
                 if (!hasEmail && !hasUsage && !signedIn) {
                     // No per-version credential. That is NOT the same as unusable: Claude
                     // Code authenticates from `CLAUDE_CODE_OAUTH_TOKEN` when the

package/dist/commands/watchdog.js

@@ -24,6 +24,7 @@ import { parseDuration } from '../lib/hooks/cache.js';
 import { getRuntimeStateDir } from '../lib/state.js';
 import { readJob, setJobEnabled } from '../lib/routines.js';
 import { getActiveSessions } from '../lib/session/active.js';
+import { loadLocalActiveSessions } from '../lib/session/session-cache.js';
 import { mailboxIdForActiveSession } from '../lib/mailbox-target.js';
 import { gcMailbox } from '../lib/mailbox-gc.js';
 import { devicesWithRoutineEnabled, routineEnabledOnThisDevice } from '../lib/routine-activation.js';
@@ -151,9 +152,19 @@ export function registerWatchdogCommand(program) {
             stateDir: stateDir(),
             sessions,
         });
+        // RUSH-2062: share the daemon-warmed local active-session snapshot with
+        // menubar/CLI/Factory instead of re-running a full gather every tick.
+        const loadWatchdogSessions = async () => {
+            const loaded = await loadLocalActiveSessions({
+                // Force a live gather only when the warm path is unavailable; the
+                // cache layer already re-gathers past DEFAULT_ACTIVE_CACHE_MAX_AGE_MS.
+                gather: () => getActiveSessions({ localOnly: true }),
+            });
+            return loaded.sessions;
+        };
         if (!opts.watch) {
             const willInject = computeWillInject();
-            const sessions = await getActiveSessions();
+            const sessions = await loadWatchdogSessions();
             const result = await tickOnce(willInject, sessions);
             await runMailboxGc(sessions);
             if (opts.json)
@@ -172,7 +183,7 @@ export function registerWatchdogCommand(program) {
         while (true) {
             // Re-evaluated each tick: picks up enable/disable flips mid-run.
             const willInject = computeWillInject();
-            const sessions = await getActiveSessions();
+            const sessions = await loadWatchdogSessions();
             const result = await tickOnce(willInject, sessions);
             await runMailboxGc(sessions);
             if (opts.json)

package/dist/index.js

@@ -94,7 +94,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
@@ -941,6 +941,7 @@ async function registerAllEagerCommands() {
     await reg(loadDefaults);
     await reg(loadSet);
     await reg(loadModels);
+    await reg(loadModes);
     await reg(loadPrune);
     await reg(loadTrash);
     await reg(loadRestore);

package/dist/lib/agent-modes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Permission-mode catalog for a harness.
+ *
+ * Source of truth is AGENTS[id].capabilities.modes plus the native CLI flags
+ * in AGENT_COMMANDS.modeFlags. This is the modes analog of the model catalog
+ * (`agents models`) — what a human or orchestrating agent reads before
+ * `agents run <agent> --mode …` / `agents teams add … --mode …`.
+ */
+import type { AgentId, Mode } from './types.js';
+/** Human description for each canonical permission mode. */
+export declare const MODE_DESCRIPTIONS: Record<Mode, string>;
+export interface AgentModeEntry {
+    mode: Mode;
+    /** Native CLI flags agents-cli forwards for this mode (empty = harness default). */
+    flags: string[];
+    description: string;
+    /** First entry in capabilities.modes — the safest native mode. */
+    isDefault: boolean;
+}
+export interface AgentModesCatalog {
+    agent: AgentId;
+    /** Modes this harness natively supports, in declaration order. */
+    modes: AgentModeEntry[];
+    /** capabilities.modes[0] — safest native mode; run may still default elsewhere (e.g. CLI plan, teams edit). */
+    defaultMode: Mode;
+    /**
+     * Configured run.defaults mode for this agent@version, when set.
+     * Null means no pin — CLI default (plan for most harnesses) or modes[0] applies.
+     */
+    configuredMode: Mode | null;
+    configuredModeSource: string | null;
+    /**
+     * Whether plan works in a headless (`-p` / prompt) run. false means a headless
+     * --mode plan degrades (see resolveHeadlessMode). undefined = assumed true.
+     */
+    headlessPlan: boolean;
+    /** Canonical modes this harness does NOT list in capabilities.modes. */
+    unsupported: Mode[];
+    /** Notes an orchestrator should read before picking a mode. */
+    notes: string[];
+}
+/**
+ * Build the permission-mode catalog for one harness.
+ * `version` only affects the configured run.defaults lookup (modes themselves
+ * are per-agent today, not version-gated).
+ */
+export declare function getAgentModesCatalog(agent: AgentId, version?: string | null, cwd?: string): AgentModesCatalog;
+/** Format native flags for display, e.g. `--permission-mode plan` or `(harness default)`. */
+export declare function formatModeFlags(flags: string[]): string;