@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## Unreleased
+
+## 1.20.5
+
+**`agents inspect` — per-agent+version detail view with drill-down (#217)**
+
+- New top-level command `agents inspect <agent>[@version]`. Summary mode shows install path, config symlink target, shim path, versioned alias, run strategy, capability table (`hooks`/`mcp`/`skills`/`commands`/`subagents`/`plugins`/`workflows`/`rules`/`allowlist`), resource counts with project/user/system scope breakdown, and session total. Replaces the awkward `agents view <agent>@<version>` deep-detail mode as a dedicated verb; `view` itself is unchanged.
+- Drill-down flags for every resource kind — `--commands`, `--skills`, `--hooks`, `--mcp`, `--rules`, `--plugins`, `--workflows`, `--subagents`. Bare flag lists every entry; passing a positional query fuzzy-searches that kind, ranking exact > substring > Damerau-Levenshtein. Zero matches exit 1 with the three closest names as suggestions. One drill-down at a time (validation error otherwise). `--json` works with summary and every drill-down for scriptable consumption.
+- Resource names render as OSC-8 terminal hyperlinks to the marker file (`SKILL.md` / `WORKFLOW.md` / `AGENT.md`) for clickable navigation in modern terminals (Ghostty, iTerm2, WezTerm) — no inline path noise. Plain text on terminals without OSC-8 support.
+- MCP detail intentionally suppresses path and env values to avoid leaking secrets — only the server name, scope, and version reach the output.
+- Removes the deprecated `agents status` alias for `view @default`. Top-level help text updated; no consumers referenced it.
+
+**Headless Linux: encrypted-file fallback when libsecret collection is locked (#183)**
+
+- On server-class Linux (Ubuntu 24.04 over SSH on the reporter's box), `agents secrets create x` failed with `secret-tool: Cannot create an item in a locked collection`. Diagnosis in the issue: `gnome-keyring-daemon` is running and D-Bus is reachable, but the default `login` collection is locked because no graphical login has fed the daemon the passphrase, and `secret-tool` from `libsecret-tools` has no `--collection` flag so it can't target the unlocked `session` collection. This made `agents secrets` effectively macOS-only on any headless box.
+- `src/lib/secrets/linux.ts` now transparently falls back to a file-based AES-256-GCM encrypted store at `~/.agents/.cache/secrets/<item>.enc` (mode 0600, per-file random scrypt salt + 96-bit IV, GCM auth tag). The encryption key is scrypt-derived from a passphrase read from `AGENTS_SECRETS_PASSPHRASE` (preferred) or a TTY prompt via `/dev/tty` with `stty -echo` for non-echoing input. The fallback also activates when `libsecret-tools` is not installed at all but `AGENTS_SECRETS_PASSPHRASE` is set, so a fresh install can store secrets without any apt-get step.
+- The decision is cached per process; on first activation we emit one stderr line: `[agents] secret-service collection locked, using file-based store at <dir>`. The `KeychainBackend` interface in `src/lib/secrets/index.ts` is unchanged — `has`/`get`/`set`/`delete`/`list` work identically against either backend, so `bundles.ts`, `sync.ts`, and every consumer above it sees no API change.
+- Items written into the file store before the fallback was added remain accessible only via libsecret if/when the collection is later unlocked; this PR does not migrate stranded items in either direction — the user simply re-creates them on a freshly headless box.
+
 ## 1.20.4
 
 **Plugin marketplace sync (skip outside-pointing symlinks)**

package/README.md

@@ -243,7 +243,7 @@ agents teams status auth-feature    # Who's working, what they changed, what the
 
 Teammates run detached -- close your terminal, they keep working. Check in with `teams status`, read full output with `teams logs <name>`, clean up with `teams disband`.
 
-Team state is observable via `agents teams list --json` / `agents teams status --json`. External tools join it with `sessions --json` (teammates get `isTeamOrigin: true`) and `cloud list --json` (for `--cloud` teammates) to build a unified fleet view. See [docs/06-observability.md](docs/06-observability.md).
+Team state is observable via `agents teams list --json` / `agents teams status --json` (compact by default; add `--verbose` for the full per-teammate shape). External tools join it with `sessions --json` (teammates get `isTeamOrigin: true`) and `cloud list --json` (for `--cloud` teammates) to build a unified fleet view. See [docs/06-observability.md](docs/06-observability.md).
 
 ---
 
@@ -641,23 +641,54 @@ By default, secrets sync via iCloud Keychain to your other Macs. With `--no-iclo
 
 ## Compatibility
 
-| Agent | Versions | MCP | Commands | Skills | Rules | Hooks | Plugins | Permissions | Routines | Teams |
-|-------|----------|-----|----------|--------|-------|-------|---------|-------------|----------|-------|
-| Claude Code | yes | yes | yes | yes | CLAUDE.md | yes | yes | yes | yes | yes |
-| Codex CLI | yes | yes | yes | yes | AGENTS.md | yes (>= 0.116.0) | -- | yes | yes | yes |
-| Gemini CLI | yes | yes | yes | yes | GEMINI.md | yes (>= 0.26.0) | -- | -- | yes | yes |
-| OpenClaw | yes | yes | -- | yes | workspace/AGENTS.md | yes | yes | -- | -- | -- |
-| Cursor | yes | yes | yes | yes | .cursorrules | -- | -- | -- | -- | yes |
-| OpenCode | yes | yes | yes | yes | AGENTS.md | -- | -- | yes | -- | yes |
-| Copilot | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-| Amp | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-| Kiro | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-| Goose | yes | yes | -- | -- | AGENTS.md | -- | -- | -- | -- | -- |
-| Roo Code | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-
-Hooks columns marked `yes (>= X.Y.Z)` are version-gated: `agents hooks add` skips with a clear message when the installed binary is older than the listed version, instead of writing config the older binary would silently ignore. OpenCode's plugin-based hook system is on the roadmap; the entry is `--` until a writer ships.
-
-Codex command sync is version-aware: Codex `0.116.x` and older receive slash commands in `.codex/prompts/`; Codex `0.117.0+` receives those commands as generated skills so they can be invoked with `$name`.
+Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/agents.ts](src/lib/agents.ts) (`capabilities`); gates use `supports(agent, cap, version)` from [src/lib/capabilities.ts](src/lib/capabilities.ts). Full matrix also in [docs/00-concepts.md](docs/00-concepts.md).
+
+| Agent | Versions | Hooks | MCP | Permissions | Skills | Commands | Plugins | Subagents | Rules | Workflows |
+|-------|----------|-------|-----|-------------|--------|----------|---------|-----------|-------|-----------|
+| Claude Code | yes | yes | yes | yes | yes | yes | yes | yes | `CLAUDE.md` | yes |
+| Codex CLI | yes | >= 0.116.0 | yes | no | yes | < 0.117.0 · skills ($name, >= 0.117) | >= 0.128.0 | no | `AGENTS.md` | no |
+| Gemini CLI | yes | >= 0.26.0 | yes | no | yes | yes (.toml) | no | no | `GEMINI.md` | no |
+| Antigravity | yes | yes | yes | yes | yes | yes | yes | no | `AGENTS.md` | no |
+| Grok Build | yes | yes | yes | yes | yes | skills ($name) | yes | no | `AGENTS.md` | no |
+| OpenClaw | yes | yes | yes | no | yes | gateway | yes | yes | `workspace/AGENTS.md` | no |
+| Cursor | yes | no | yes | no | yes | yes | no | no | `.cursorrules` | no |
+| OpenCode | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Copilot | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Amp | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Kiro | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Goose | yes | no | yes | no | no | no | no | no | `AGENTS.md` | no |
+| Roo Code | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+
+**Legend:** `yes` / `no` = synced or skipped at install time. `skills ($name)` = no file-based slash-command dir; behavior ships as a generated skill invoked with `$command`. `gateway` = OpenClaw resolves slash commands at runtime, not from synced files. Version suffixes are enforced at sync time — out-of-range versions are skipped with a clear message.
+
+**Host CLIs** (`agents cli`) are separate: YAML manifests under `~/.agents/cli/` install binaries onto your PATH (`gh`, `higgsfield`, etc.). They are not copied into per-agent version homes.
+
+### agents-cli features (not agent-native resources)
+
+| Agent | Routines | Teams | Session index |
+|-------|----------|-------|---------------|
+| Claude Code | yes | yes | yes |
+| Codex CLI | yes | yes | yes |
+| Gemini CLI | yes | yes | yes |
+| Cursor | -- | yes | -- |
+| OpenCode | -- | yes | -- |
+| Grok Build | -- | yes | yes |
+| Antigravity | -- | yes | -- |
+| Copilot | -- | -- | yes |
+| OpenClaw, Amp, Kiro, Goose, Roo | -- | -- | -- |
+
+### Version-gated sync
+
+| Capability | Agent | Gate |
+|------------|-------|------|
+| Hooks | Codex | >= 0.116.0 |
+| Hooks | Gemini | >= 0.26.0 |
+| File-based commands | Codex | < 0.117.0 (0.117+ uses command-as-skill) |
+| Plugins | Codex | >= 0.128.0 |
+
+Codex `0.117.0+` no longer reads `.codex/prompts/`; agents-cli converts slash commands into skills so they stay invocable as `$name`. OpenCode's plugin-based hook system is on the roadmap; hooks stay `no` until a writer ships.
+
+Slash commands can declare per-agent/version targeting in frontmatter (`agents:`, `since:`, `until:`). Gating applies when syncing from `~/.agents/commands/` (user/system) into version homes — project `.agents/commands/` files are read in place and are not filtered by `agents:`. This repo ships `.agents/commands/version.md` as `/version` for Claude, Codex, Gemini, Cursor, OpenCode, Copilot, and Grok; Antigravity excluded until verified.
 
 ## FAQ
 

package/dist/commands/browser.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { listProfiles, getProfile, createProfile, deleteProfile, ensureDefaultBrowserProfile, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, } from '../lib/browser/profiles.js';
-import { findBrowserPath, getPortOccupant } from '../lib/browser/chrome.js';
+import { findBrowserPath, getPortOccupant, isLauncherScript } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
@@ -311,10 +311,28 @@ function registerProfilesCommands(browser) {
             process.exit(1);
         }
         const checks = [];
-        // 1. Binary exists for declared browser type
+        // 1. Binary exists for declared browser type, and is a real executable we
+        //    can drive — not a distro launcher script. findBrowserPath already
+        //    unwraps the known Chromium wrappers to their ELF; if it still hands
+        //    back a shebang script we couldn't resolve, `start` would fail with
+        //    `CDP connection closed` (the wrapper re-execs the browser as a child,
+        //    breaking the --remote-debugging-pipe transport — issue #229). Flag it
+        //    here instead of letting launch fail opaquely.
         try {
             const binPath = findBrowserPath(profile.browser, profile.binary);
-            checks.push({ label: 'binary', ok: true, detail: binPath });
+            if (isLauncherScript(binPath)) {
+                checks.push({
+                    label: 'binary',
+                    ok: false,
+                    detail: `${binPath} is a launcher script, not the browser executable — ` +
+                        `agents browser drives the browser over --remote-debugging-pipe and ` +
+                        `can't attach to a wrapper that re-execs it. Point the profile at the ` +
+                        `real binary (\`--binary /path/to/browser\`) or reinstall the standard package.`,
+                });
+            }
+            else {
+                checks.push({ label: 'binary', ok: true, detail: binPath });
+            }
         }
         catch (err) {
             checks.push({
@@ -351,7 +369,16 @@ function registerProfilesCommands(browser) {
         else {
             const occupant = getPortOccupant(port);
             if (!occupant) {
-                checks.push({ label: 'port', ok: true, detail: `${port} is free` });
+                // A free port doesn't mean "ready to launch here": for a local
+                // profile we self-launch over an internal --remote-debugging-pipe and
+                // never bind this port. The port is consulted only to attach to a
+                // browser someone already started on it. Say so, so a green doctor
+                // can't be read as "the port is what launch depends on" (#229).
+                checks.push({
+                    label: 'port',
+                    ok: true,
+                    detail: `${port} free — will self-launch over an internal pipe (port used only to attach to an already-running browser)`,
+                });
             }
             else {
                 try {

package/dist/commands/cli.js

@@ -52,7 +52,7 @@ Examples:
   agents cli check
 
 When to use:
-  - After 'agents pull' on a new machine, to materialize host binaries
+  - After 'agents repo refresh' on a new machine, to materialize host binaries
   - In a team setup: commit cli/ entries so teammates get the same toolchain
 `);
     cliCmd

package/dist/commands/cloud.js

@@ -123,7 +123,7 @@ Examples:
   # Codex Cloud
   agents cloud run "add auth tests" --provider codex --env env_abc123
 
-  # Default provider (set in ~/.agents-system/agents.yaml)
+  # Default provider (set in ~/.agents/agents.yaml)
   agents cloud run "refactor auth module" --repo user/repo
 `)
         .action(async (positionalPrompt, options) => {

package/dist/commands/commands.js

@@ -506,6 +506,8 @@ function buildCommandRows(opts) {
                 status = 'synced';
             else if (diff.toUpdate.includes(name))
                 status = 'stale';
+            else if (diff.toRemove.includes(name))
+                status = 'stale';
             else
                 status = 'missing';
             targets.push({

package/dist/commands/computer.js

@@ -12,8 +12,16 @@ const COMPUTER_HELP_GROUPS = [
 ];
 export function registerComputerCommand(program) {
     const computer = program
-        .command('computer')
-        .description('Drive macOS apps via Accessibility — list, screenshot, click, type');
+        .command('computers')
+        .description('Drive macOS apps via Accessibility — list, screenshot, click, type (macOS only)')
+        // The whole subsystem is macOS Accessibility / TCC. Fail fast with a clear
+        // message on other platforms instead of a downstream ENOENT / launchctl error.
+        .hook('preAction', () => {
+        if (process.platform !== 'darwin') {
+            console.error('agents computers: macOS only — it drives apps via the macOS Accessibility API.');
+            process.exit(1);
+        }
+    });
     registerComputerSubcommands(computer);
     registerCommandGroups(computer, COMPUTER_HELP_GROUPS);
 }

package/dist/commands/defaults.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Defaults command tree.
+ *
+ * `agents defaults run ...` manages selector-based defaults for `agents run`.
+ */
+import type { Command } from 'commander';
+export declare function registerDefaultsCommands(program: Command): void;

package/dist/commands/defaults.js

@@ -0,0 +1,89 @@
+/**
+ * Defaults command tree.
+ *
+ * `agents defaults run ...` manages selector-based defaults for `agents run`.
+ */
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { listRunDefaults, setRunDefault, unsetRunDefault, } from '../lib/run-defaults.js';
+function formatRunDefault(entry) {
+    const parts = [];
+    if (entry.defaults.mode)
+        parts.push(`mode ${chalk.white(entry.defaults.mode)}`);
+    if (entry.defaults.model)
+        parts.push(`model ${chalk.white(entry.defaults.model)}`);
+    return `${chalk.cyan(entry.selector.padEnd(22))} ${parts.join('  ')}`;
+}
+export function registerDefaultsCommands(program) {
+    const defaults = program
+        .command('defaults')
+        .description('Manage default options for agents-cli commands');
+    const run = defaults
+        .command('run')
+        .description('Manage selector-based defaults for `agents run`');
+    setHelpSections(run, {
+        examples: `
+      agents defaults run list
+      agents defaults run set 'claude:*' --mode auto --model opus
+      agents defaults run set claude@2.1.45 --mode plan --model sonnet
+      agents defaults run unset 'claude:*'
+    `,
+        notes: `
+      Selectors use <agent>:<version>. Use * for all versions of an agent.
+      Exact selectors override wildcard selectors field by field.
+      Explicit flags on agents run always win over configured defaults.
+    `,
+    });
+    run
+        .command('list')
+        .description('List configured run defaults')
+        .action(() => {
+        const entries = listRunDefaults();
+        if (entries.length === 0) {
+            console.log(chalk.gray('No run defaults configured.'));
+            console.log(chalk.gray("Set one with: agents defaults run set 'claude:*' --mode auto --model opus"));
+            return;
+        }
+        console.log(chalk.bold('Run Defaults\n'));
+        for (const entry of entries) {
+            console.log(`  ${formatRunDefault(entry)}`);
+        }
+    });
+    run
+        .command('set <selector>')
+        .description('Set defaults for an agent/version selector')
+        .option('--mode <mode>', "Default mode: plan, edit, auto, skip. 'full' accepted as alias for skip.")
+        .option('--model <model>', 'Default model or model alias, forwarded via --model')
+        .action((selector, options) => {
+        try {
+            const entry = setRunDefault(selector, {
+                ...(options.mode !== undefined ? { mode: options.mode } : {}),
+                ...(options.model !== undefined ? { model: options.model } : {}),
+            });
+            console.log(chalk.green('Set run default:'));
+            console.log(`  ${formatRunDefault(entry)}`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    run
+        .command('unset <selector>')
+        .description('Remove defaults for an agent/version selector')
+        .action((selector) => {
+        try {
+            const removed = unsetRunDefault(selector);
+            if (removed) {
+                console.log(chalk.green(`Removed run default ${selector}`));
+            }
+            else {
+                console.log(chalk.gray(`No run default matched ${selector}`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/doctor.js

@@ -310,7 +310,7 @@ function renderTargetText(report, options) {
     }
     else {
         console.log(`  Verdict: ${verdictParts.join(', ')}.`);
-        console.log(chalk.gray(`  Run \`agents sync --agent ${report.agent} --agent-version ${report.version}\` to reconcile, or \`agents prune cleanup\` to drop extras.`));
+        console.log(chalk.gray(`  Run \`agents sync ${report.agent}@${report.version}\` to reconcile, or \`agents prune cleanup\` to drop extras.`));
     }
 }
 // ─── command registration ────────────────────────────────────────────────────

package/dist/commands/exec.js

@@ -85,7 +85,7 @@ export function registerRunCommand(program) {
     `,
     });
     runCmd.action(async (agentSpec, prompt, options) => {
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef }, { resolveRunDefaults },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -94,6 +94,7 @@ export function registerRunCommand(program) {
             import('../lib/versions.js'),
             import('../lib/plugins.js'),
             import('../lib/workflows.js'),
+            import('../lib/run-defaults.js'),
         ]);
         const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
         // Parse agent@version
@@ -102,6 +103,7 @@ export function registerRunCommand(program) {
         let version = rawVersion || undefined;
         let profileEnv;
         let fromProfile = false;
+        let workflowModel;
         const cwd = options.cwd ?? process.cwd();
         if (isValidAgent(rawAgent)) {
             agent = rawAgent;
@@ -133,6 +135,10 @@ export function registerRunCommand(program) {
             //   subagents/*.md     ← flat .md files copied to ~/.claude/agents/ for Agent tool discovery
             const workflowDir = resolveWorkflowRef(rawAgent, cwd);
             agent = 'claude';
+            const workflowFrontmatter = parseWorkflowFrontmatter(workflowDir);
+            if (typeof workflowFrontmatter?.model === 'string' && workflowFrontmatter.model.trim() !== '') {
+                workflowModel = workflowFrontmatter.model.trim();
+            }
             const resolvedVersion = resolveVersionAlias('claude', version);
             const versionHome = getVersionHomePath('claude', resolvedVersion ?? getGlobalDefault('claude') ?? '');
             const claudeAgentsDir = path.join(versionHome, '.claude', 'agents');
@@ -179,8 +185,7 @@ export function registerRunCommand(program) {
             // Auto-inject secrets bundles declared in the workflow's frontmatter `secrets:` field.
             // Union with any --secrets flags the user passed; dedupe. Skip when --no-auto-secrets is set.
             if (!options.noAutoSecrets) {
-                const fm = parseWorkflowFrontmatter(workflowDir);
-                const declared = fm?.secrets ?? [];
+                const declared = workflowFrontmatter?.secrets ?? [];
                 if (declared.length > 0) {
                     const existing = new Set(options.secrets);
                     const added = [];
@@ -202,10 +207,20 @@ export function registerRunCommand(program) {
             process.stderr.write(chalk.gray(`Workflow '${rawAgent}' → claude (${subagentCount} subagents)\n`));
         }
         else {
-            console.error(chalk.red(`Unknown agent: ${rawAgent}`));
-            console.error(chalk.gray(`Available agents: ${ALL_AGENT_IDS.join(', ')}`));
-            console.error(chalk.gray(`Or add a profile: agents profiles add <name>`));
-            process.exit(1);
+            // Smart pick: auto-correct a single typo (insertion/deletion/substitution/transposition)
+            // against the known agent ids before giving up. Example: `cladue` -> `claude`, `grk` -> `grok`.
+            const { fuzzyMatch, FUZZY_PRESETS } = await import('../lib/fuzzy.js');
+            const suggested = fuzzyMatch(rawAgent, ALL_AGENT_IDS, FUZZY_PRESETS.agents);
+            if (suggested && isValidAgent(suggested)) {
+                process.stderr.write(chalk.gray(`Resolved '${rawAgent}' -> '${suggested}' (single-edit match)\n`));
+                agent = suggested;
+            }
+            else {
+                console.error(chalk.red(`Unknown agent: ${rawAgent}`));
+                console.error(chalk.gray(`Available agents: ${ALL_AGENT_IDS.join(', ')}`));
+                console.error(chalk.gray(`Or add a profile: agents profiles add <name>`));
+                process.exit(1);
+            }
         }
         version = resolveVersionAlias(agent, version);
         const configuredStrategy = getConfiguredRunStrategy(agent, cwd);
@@ -252,22 +267,44 @@ export function registerRunCommand(program) {
                 }
             }
         }
+        const defaultVersion = version ?? resolveVersion(agent, cwd);
+        const runDefaults = fromProfile
+            ? { sources: {} }
+            : resolveRunDefaults(agent, defaultVersion, cwd);
         // Accept the four canonical modes plus 'full' as a permanent silent
         // alias for 'skip' (rewritten downstream by normalizeMode in exec.ts).
-        const mode = options.mode;
+        let mode = options.mode;
+        const modeSource = runCmd.getOptionValueSource('mode');
+        const modeFromRunDefault = modeSource === 'default' && !!runDefaults.mode;
+        if (modeFromRunDefault) {
+            mode = runDefaults.mode;
+        }
         if (!['plan', 'edit', 'auto', 'skip', 'full'].includes(mode)) {
             console.error(chalk.red(`Invalid mode: ${mode}. Use plan, edit, auto, or skip ('full' accepted as alias for skip).`));
             process.exit(1);
         }
-        // Surface capability errors as a clean CLI message instead of a stack
-        // trace from buildExecCommand. resolveMode degrades 'auto' silently and
-        // throws on unsupported 'plan'/'skip' — we catch and pretty-print.
+        // When the user did not pass --mode explicitly, the default is the
+        // generic 'plan'. Some agents (antigravity: edit/skip only, grok in some
+        // configurations) do not support plan. For implicit defaults, degrade
+        // silently to the agent's first listed mode rather than throwing — the
+        // user did not ask for read-only, they asked for "just run it." An
+        // explicit --mode plan still throws (see resolveMode), because silently
+        // elevating an explicit read-only request to edit is unsafe.
+        const modeIsDefault = modeSource === 'default';
         try {
             resolveMode(agent, normalizeMode(mode));
         }
         catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
+            if (modeIsDefault && !modeFromRunDefault) {
+                mode = defaultModeFor(agent);
+                if (!options.quiet) {
+                    process.stderr.write(chalk.gray(`[agents] ${agent} has no '${options.mode}' mode; using '${mode}'\n`));
+                }
+            }
+            else {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
         }
         const effort = options.effort;
         if (!['low', 'medium', 'high', 'xhigh', 'max', 'auto'].includes(effort)) {
@@ -310,6 +347,11 @@ export function registerRunCommand(program) {
         const env = hasOverrides
             ? { ...(profileEnv ?? {}), ...secretsEnv, ...(userEnv ?? {}) }
             : undefined;
+        const modelSource = runCmd.getOptionValueSource('model');
+        const model = options.model
+            ?? (!fromProfile && modelSource === undefined
+                ? (workflowModel ?? (options.fallback ? undefined : runDefaults.model))
+                : undefined);
         const execOptions = {
             agent,
             version,
@@ -318,7 +360,7 @@ export function registerRunCommand(program) {
             mode,
             effort,
             cwd: options.cwd,
-            model: options.model,
+            model,
             addDirs: options.addDir,
             json: options.json,
             headless: options.headless ?? true,
@@ -344,12 +386,24 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
             const entries = options.fallback.split(',').map(s => s.trim()).filter(Boolean);
+            const { fuzzyMatch: fuzzyFb, FUZZY_PRESETS: PRESETS_FB } = await import('../lib/fuzzy.js');
             for (const entry of entries) {
-                const [fbAgent, fbVersion] = entry.split('@');
-                if (!isValidAgent(fbAgent)) {
-                    console.error(chalk.red(`Unknown fallback agent: ${fbAgent}`));
-                    console.error(chalk.gray(`Available: ${ALL_AGENT_IDS.join(', ')}`));
-                    process.exit(1);
+                const [rawFbAgent, fbVersion] = entry.split('@');
+                let fbAgent;
+                if (isValidAgent(rawFbAgent)) {
+                    fbAgent = rawFbAgent;
+                }
+                else {
+                    const suggested = fuzzyFb(rawFbAgent, ALL_AGENT_IDS, PRESETS_FB.agents);
+                    if (suggested && isValidAgent(suggested)) {
+                        process.stderr.write(chalk.gray(`Resolved fallback '${rawFbAgent}' -> '${suggested}' (single-edit match)\n`));
+                        fbAgent = suggested;
+                    }
+                    else {
+                        console.error(chalk.red(`Unknown fallback agent: ${rawFbAgent}`));
+                        console.error(chalk.gray(`Available: ${ALL_AGENT_IDS.join(', ')}`));
+                        process.exit(1);
+                    }
                 }
                 if (fbAgent === agent) {
                     console.error(chalk.red(`Fallback cannot include the primary agent (${agent}). Rate-limit fallback only helps when switching providers.`));

package/dist/commands/hooks.js

@@ -4,8 +4,8 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { checkbox } from '@inquirer/prompts';
-import { AGENTS, HOOKS_CAPABLE_AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
-import { supports } from '../lib/capabilities.js';
+import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
+import { supports, capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverHooksFromRepo, installHooksCentrally, listCentralHooks, listInstalledHooksWithScope, getHookInfo, parseHookManifest, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
@@ -58,7 +58,7 @@ When to use:
             agentId = resolveAgentName(agentName);
             if (!agentId) {
                 spinner.stop();
-                console.log(chalk.red(formatAgentError(agentName, [...HOOKS_CAPABLE_AGENTS])));
+                console.log(chalk.red(formatAgentError(agentName, [...capableAgents('hooks')])));
                 process.exit(1);
             }
             requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
@@ -185,7 +185,7 @@ When to use:
         }
         // No agent specified - show default version for each hooks-capable agent
         console.log(chalk.bold('Installed Hooks\n'));
-        for (const aid of HOOKS_CAPABLE_AGENTS) {
+        for (const aid of capableAgents('hooks')) {
             const agent = AGENTS[aid];
             const installedVersions = listInstalledVersions(aid);
             const defaultVer = getGlobalDefault(aid);
@@ -338,7 +338,7 @@ Examples:
             // Get agent and version selection
             let selectedAgents;
             let versionSelections;
-            const hooksCapableAgents = Array.from(HOOKS_CAPABLE_AGENTS);
+            const hooksCapableAgents = Array.from(capableAgents('hooks'));
             if (options.agents) {
                 const result = await resolveAgentTargetsAutoInstalling(options.agents, hooksCapableAgents, { yes: options.yes });
                 if (!result) {
@@ -468,7 +468,7 @@ Examples:
             // agent@x.y.z, agent@all, literal all) works here too.
             let availableTargets = hookInfo.targets;
             if (options?.agents) {
-                const requestedTargets = resolveInstalledAgentTargets(options.agents, [...HOOKS_CAPABLE_AGENTS]);
+                const requestedTargets = resolveInstalledAgentTargets(options.agents, [...capableAgents('hooks')]);
                 const requested = new Set();
                 for (const aid of requestedTargets.directAgents) {
                     for (const ver of listInstalledVersions(aid)) {

package/dist/commands/inspect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `agents inspect <agent>[@version]` — single-agent, single-version detail view.
+ *
+ * Summary mode shows the per-version header (paths, shim, capabilities, resource
+ * counts, sessions). Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...) list
+ * one resource kind; passing a positional query to the same flag fuzzy-searches
+ * for a single resource and prints its detail. Resource names render as OSC-8
+ * hyperlinks to the marker file (SKILL.md / WORKFLOW.md / AGENT.md / the file
+ * itself) so users can click straight to the source.
+ */
+import { Command } from 'commander';
+interface InspectOptions {
+    brief?: boolean;
+    json?: boolean;
+    commands?: boolean | string;
+    skills?: boolean | string;
+    hooks?: boolean | string;
+    mcp?: boolean | string;
+    rules?: boolean | string;
+    plugins?: boolean | string;
+    workflows?: boolean | string;
+    subagents?: boolean | string;
+}
+export declare function registerInspectCommand(program: Command): void;
+export declare function inspectAction(target: string, options: InspectOptions): Promise<void>;
+export {};