@phnx-labs/agents-cli 1.20.5 → 1.20.7

package/dist/lib/secrets/install-helper.js

@@ -14,14 +14,23 @@
  */
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
+import { createHash } from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 const APP_BUNDLE_NAME = 'Agents CLI.app';
 const INSTALL_DIR_NAME = 'agents-cli';
+let installRootOverride = null;
+/** Redirect the install root (test only). Returns the previous override so callers can restore. */
+export function setInstallRootForTest(dir) {
+    const prev = installRootOverride;
+    installRootOverride = dir;
+    return prev;
+}
 /** Absolute path to the installed `.app` bundle directory (not the executable). */
 function installedAppPath() {
-    return path.join(os.homedir(), 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
+    const root = installRootOverride ?? os.homedir();
+    return path.join(root, 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
 }
 /** Absolute path to the executable inside the installed `.app` bundle. */
 function installedExecutablePath() {
@@ -57,6 +66,33 @@ function assertDarwin() {
         throw new Error('Keychain helper is macOS only.');
     }
 }
+function sha256File(filePath) {
+    return createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+/**
+ * True when the installed helper executable differs byte-for-byte from the
+ * bundled source helper. A stale-but-validly-signed helper is exactly how the
+ * broken 1.20.4 build (signed, but missing the keychain-access-groups
+ * entitlement) survived upgrades: codesign --verify passes on it, so the
+ * "exists and verifies" early-return kept it installed forever. Returns false
+ * when there is no bundled source to compare against (dev installs) or no
+ * installed copy yet — both cases are decided by the existence checks in the
+ * callers, not by staleness.
+ */
+function installedHelperIsStale() {
+    let srcApp;
+    try {
+        srcApp = sourceAppPath();
+    }
+    catch {
+        return false;
+    }
+    const srcExec = path.join(srcApp, 'Contents', 'MacOS', 'Agents CLI');
+    const destExec = installedExecutablePath();
+    if (!fs.existsSync(srcExec) || !fs.existsSync(destExec))
+        return false;
+    return sha256File(srcExec) !== sha256File(destExec);
+}
 function codesignVerify(appPath) {
     const r = spawnSync('codesign', ['--verify', '--deep', '--strict', appPath], {
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -86,8 +122,10 @@ function copyAppBundle(src, dest) {
 }
 /**
  * Idempotent install. Copies the bundled `.app` to the stable user path. Skips
- * if the destination already exists and `codesign --verify` passes, unless
- * `forceReinstall=true`.
+ * if the destination already exists, `codesign --verify` passes, AND the
+ * installed executable matches the bundled one byte-for-byte — a valid
+ * signature alone is not enough, because an outdated helper signs clean too.
+ * `forceReinstall=true` skips all checks and always copies.
  *
  * Notarization is checked via `spctl --assess` after install — a failure is
  * logged as a warning but does NOT throw. Notarization checks require network
@@ -99,7 +137,7 @@ export function ensureKeychainHelperInstalled(opts = {}) {
     const dest = installedAppPath();
     if (!opts.forceReinstall && fs.existsSync(dest)) {
         const { ok } = codesignVerify(dest);
-        if (ok)
+        if (ok && !installedHelperIsStale())
             return;
     }
     const src = sourceAppPath();
@@ -119,14 +157,18 @@ export function ensureKeychainHelperInstalled(opts = {}) {
 }
 /**
  * Return the absolute path to the helper executable. If the installed bundle
- * is missing, performs a lazy install first.
+ * is missing, or is stale relative to the bundled source helper, performs a
+ * lazy (re)install first. The staleness check is what lets an upgraded CLI
+ * replace a helper a previous version installed — `agents helper install`
+ * never runs on `npm i -g`, so this call site is the only one every machine
+ * is guaranteed to pass through.
  *
  * Throws on non-darwin.
  */
 export function getKeychainHelperPath() {
     assertDarwin();
     const exec = installedExecutablePath();
-    if (!fs.existsSync(exec)) {
+    if (!fs.existsSync(exec) || installedHelperIsStale()) {
         ensureKeychainHelperInstalled();
     }
     return exec;

package/dist/lib/secrets/linux.d.ts

@@ -43,6 +43,18 @@ export declare function hasSecretToolToken(item: string): boolean;
 export declare function getSecretToolToken(item: string): string;
 export declare function setSecretToolToken(item: string, value: string): void;
 export declare function deleteSecretToolToken(item: string): boolean;
+/**
+ * Parse the item names out of `secret-tool search --all` output, keeping only
+ * those starting with `prefix`. Exported for tests.
+ *
+ * `output` must be the combined stdout+stderr of the search: libsecret splits
+ * the dump across both streams — the value/label/schema lines go to stdout
+ * while the `attribute.*` lines (which carry `attribute.item`, the only place
+ * the item name is reliably machine-readable) go to stderr (observed on
+ * libsecret 0.21.4). Which stream each line lands on has varied across
+ * libsecret versions, so callers concatenate both rather than bet on one.
+ */
+export declare function parseSecretToolItems(output: string, prefix: string): string[];
 /**
  * List secrets by prefix. secret-tool doesn't have a list command,
  * so we use secret-tool search which outputs in a specific format.

package/dist/lib/secrets/linux.js

@@ -345,6 +345,34 @@ export function deleteSecretToolToken(item) {
     // surface that rather than silently swallowing.
     return false;
 }
+/**
+ * Parse the item names out of `secret-tool search --all` output, keeping only
+ * those starting with `prefix`. Exported for tests.
+ *
+ * `output` must be the combined stdout+stderr of the search: libsecret splits
+ * the dump across both streams — the value/label/schema lines go to stdout
+ * while the `attribute.*` lines (which carry `attribute.item`, the only place
+ * the item name is reliably machine-readable) go to stderr (observed on
+ * libsecret 0.21.4). Which stream each line lands on has varied across
+ * libsecret versions, so callers concatenate both rather than bet on one.
+ */
+export function parseSecretToolItems(output, prefix) {
+    const items = [];
+    // Parse output format:
+    // [/org/freedesktop/secrets/collection/login/1]
+    // label = agents-cli: myitem
+    // ...
+    // attribute.item = myitem
+    const itemRegex = /attribute\.item\s*=\s*(.+)/g;
+    let match;
+    while ((match = itemRegex.exec(output)) !== null) {
+        const itemName = match[1].trim();
+        if (itemName.startsWith(prefix)) {
+            items.push(itemName);
+        }
+    }
+    return [...new Set(items)]; // dedupe
+}
 /**
  * List secrets by prefix. secret-tool doesn't have a list command,
  * so we use secret-tool search which outputs in a specific format.
@@ -365,22 +393,8 @@ export function listSecretToolItems(prefix) {
         }
         return [];
     }
-    const output = result.stdout?.toString() || '';
-    const items = [];
-    // Parse output format:
-    // [/org/freedesktop/secrets/collection/login/1]
-    // label = agents-cli: myitem
-    // ...
-    // attribute.item = myitem
-    const itemRegex = /attribute\.item\s*=\s*(.+)/g;
-    let match;
-    while ((match = itemRegex.exec(output)) !== null) {
-        const itemName = match[1].trim();
-        if (itemName.startsWith(prefix)) {
-            items.push(itemName);
-        }
-    }
-    return [...new Set(items)]; // dedupe
+    const output = `${result.stdout?.toString() || ''}\n${result.stderr?.toString() || ''}`;
+    return parseSecretToolItems(output, prefix);
 }
 /** KeychainBackend implementation for Linux. Routes through secret-tool
  *  with a transparent encrypted-file fallback when the default Secret

package/dist/lib/session/artifacts.js

@@ -8,6 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { parseSession } from './parse.js';
+import { toComparablePath } from '../platform/index.js';
 /** Tool names that produce file artifacts (writes, edits, patches). */
 const WRITE_TOOLS = new Set([
     'Write', 'Edit', 'write_file', 'edit_file', 'create_file', 'replace', 'patch',
@@ -87,8 +88,13 @@ export function resolveArtifact(artifacts, name) {
         return byBase[0];
     if (byBase.length > 1)
         return byBase[0];
-    // Path suffix match (e.g. "src/foo.ts")
-    const bySuffix = artifacts.filter(a => a.path.endsWith('/' + name) || a.path === name);
+    // Path suffix match (e.g. "src/foo.ts"). Normalize so Windows `\` paths match
+    // a forward-slash query too; on POSIX this is identical to the old comparison.
+    const target = toComparablePath(name);
+    const bySuffix = artifacts.filter(a => {
+        const ap = toComparablePath(a.path);
+        return ap.endsWith('/' + target) || ap === target;
+    });
     if (bySuffix.length >= 1)
         return bySuffix[0];
     return null;

package/dist/lib/shims.d.ts

@@ -68,8 +68,16 @@ export interface ConflictInfo {
  *         scoped plugin marketplaces (agents-cli/agents-system/extras-<alias>/
  *         agents-project). Version-home reconciliation stays out of the hot
  *         path — management commands still own that.
+ *   v17 — bash-side skip-fast sentinel under ~/.agents/.cache/launch-sync/.
+ *         When the sentinel mtime is newer than every source dir, exec the
+ *         agent binary directly without spawning node. Cuts steady-state
+ *         hot-path latency from ~680ms (node startup + module init) to ~11ms
+ *         (a few stat calls). Node writes the sentinel after each successful
+ *         sync. Documented limitation: POSIX dir mtime only updates on
+ *         top-level entry add/remove — deep edits to plugin contents won't
+ *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 16;
+export declare const SHIM_SCHEMA_VERSION = 17;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -13,6 +13,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { fileURLToPath } from 'url';
 import { confirm, select } from '@inquirer/prompts';
+import { IS_WINDOWS } from './platform/index.js';
 import { getShimsDir, getVersionsDir, getBackupsDir, ensureAgentsDir } from './state.js';
 export { getShimsDir };
 import { AGENTS } from './agents.js';
@@ -192,8 +193,16 @@ async function promptConflictStrategy(conflictInfos) {
  *         scoped plugin marketplaces (agents-cli/agents-system/extras-<alias>/
  *         agents-project). Version-home reconciliation stays out of the hot
  *         path — management commands still own that.
+ *   v17 — bash-side skip-fast sentinel under ~/.agents/.cache/launch-sync/.
+ *         When the sentinel mtime is newer than every source dir, exec the
+ *         agent binary directly without spawning node. Cuts steady-state
+ *         hot-path latency from ~680ms (node startup + module init) to ~11ms
+ *         (a few stat calls). Node writes the sentinel after each successful
+ *         sync. Documented limitation: POSIX dir mtime only updates on
+ *         top-level entry add/remove — deep edits to plugin contents won't
+ *         trigger auto-resync, run `agents sync` for that.
  */
-export const SHIM_SCHEMA_VERSION = 16;
+export const SHIM_SCHEMA_VERSION = 17;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -473,8 +482,32 @@ fi
 ${managedEnv}
 
 # Project-scoped compile (rules, workspace resources, scoped plugin marketplaces).
-# Filesystem-only — sub-50ms steady state. Never blocks launch on failure.
-"$AGENTS_BIN" sync --agent "$AGENT" --agent-version "$VERSION" --launch --cwd "$PWD" --quiet 2>/dev/null || true
+# Skip-fast: if a sentinel from the last sync exists and is newer than all
+# source dirs (project .agents/, user plugins, system plugins), exec the
+# agent binary directly without spawning node. Cuts steady-state hot-path
+# latency from ~680ms (node startup + agents-cli module init) to ~11ms (a
+# handful of stat calls). Never blocks launch on failure of the sync itself.
+#
+# Known limitation: POSIX dir mtime updates only on entry add/remove at that
+# level. Deep edits to existing plugin contents (e.g. editing a SKILL.md
+# inside a plugin) won't bump the parent dir's mtime — the marketplace copy
+# stays stale until \`agents sync\` runs explicitly or a top-level entry
+# changes. Advanced users hot-iterating on plugins know to run sync.
+PROJECT_SLUG=\$(printf '%s' "\$PWD" | tr / _ | tr ' ' _)
+LAUNCH_SENTINEL="\$AGENTS_USER_DIR/.cache/launch-sync/\${AGENT}@\${VERSION}@\${PROJECT_SLUG}"
+LAUNCH_SKIP=0
+if [ -f "\$LAUNCH_SENTINEL" ]; then
+  LAUNCH_SKIP=1
+  for LAUNCH_SRC in "\$PWD/.agents" "\$AGENTS_USER_DIR/plugins" "\$AGENTS_USER_DIR/.system/plugins"; do
+    if [ -e "\$LAUNCH_SRC" ] && [ "\$LAUNCH_SRC" -nt "\$LAUNCH_SENTINEL" ]; then
+      LAUNCH_SKIP=0
+      break
+    fi
+  done
+fi
+if [ "\$LAUNCH_SKIP" = "0" ]; then
+  "\$AGENTS_BIN" sync --agent "\$AGENT" --agent-version "\$VERSION" --launch --cwd "\$PWD" --quiet 2>/dev/null || true
+fi
 
 exec "$BINARY"${launchArgs} "$@"
 `;
@@ -489,8 +522,28 @@ export function createShim(agent) {
     const shimPath = path.join(shimsDir, agentConfig.cliCommand);
     const script = generateShimScript(agent);
     fs.writeFileSync(shimPath, script, { mode: 0o755 });
+    // Windows can't execute the bash shim directly. Drop a `.cmd` companion next
+    // to it that delegates to the node-side transparent resolver (`agents __shim`),
+    // so the version resolution stays single-sourced instead of reimplemented in batch.
+    if (IS_WINDOWS) {
+        writeWindowsCmdShim(shimPath + '.cmd', agentConfig.cliCommand);
+    }
     return shimPath;
 }
+/**
+ * Generate a Windows `.cmd` launcher that delegates to `agents __shim <spec>`.
+ * `spec` is the agent's cliCommand for the default-version shim, or
+ * `cliCommand@version` for a versioned alias. node + the dist entrypoint are
+ * resolved at generation time so the launcher does not depend on `agents`
+ * already being on PATH.
+ */
+function writeWindowsCmdShim(cmdPath, spec) {
+    const indexJs = getAgentsBinForGeneratedShim();
+    const content = `@echo off\r\n` +
+        `rem Auto-generated by agents-cli - do not edit\r\n` +
+        `node "${indexJs}" __shim ${spec} %*\r\n`;
+    fs.writeFileSync(cmdPath, content);
+}
 /**
  * Remove the shim for an agent.
  */
@@ -500,6 +553,12 @@ export function removeShim(agent) {
     const shimPath = path.join(shimsDir, agentConfig.cliCommand);
     if (fs.existsSync(shimPath)) {
         fs.unlinkSync(shimPath);
+        if (IS_WINDOWS) {
+            try {
+                fs.unlinkSync(shimPath + '.cmd');
+            }
+            catch { }
+        }
         return true;
     }
     return false;
@@ -650,6 +709,9 @@ export function createVersionedAlias(agent, version) {
     const aliasPath = path.join(shimsDir, `${agentConfig.cliCommand}@${version}`);
     const script = generateVersionedAliasScript(agent, version);
     fs.writeFileSync(aliasPath, script, { mode: 0o755 });
+    if (IS_WINDOWS) {
+        writeWindowsCmdShim(aliasPath + '.cmd', `${agentConfig.cliCommand}@${version}`);
+    }
     return aliasPath;
 }
 /**
@@ -661,6 +723,12 @@ export function removeVersionedAlias(agent, version) {
     const aliasPath = path.join(shimsDir, `${agentConfig.cliCommand}@${version}`);
     if (fs.existsSync(aliasPath)) {
         fs.unlinkSync(aliasPath);
+        if (IS_WINDOWS) {
+            try {
+                fs.unlinkSync(aliasPath + '.cmd');
+            }
+            catch { }
+        }
         return true;
     }
     return false;
@@ -1456,6 +1524,15 @@ Then restart your shell or run:
  * Returns true if added, false if already present or failed.
  */
 export function addShimsToPath(overrides) {
+    // Windows has no shell rc file to edit: the primary `agents` command is already
+    // on PATH via npm's global bin, and bare shorthands / versioned aliases are
+    // handled by the `.cmd` shims plus the PATH guidance printed at install time.
+    // Report "already present" so callers don't emit a misleading "added to
+    // ~/.bashrc / source ~/.bashrc" message. (The `shell` override is the test hook
+    // for exercising the POSIX path, so it bypasses this short-circuit.)
+    if (IS_WINDOWS && !overrides?.shell) {
+        return { success: true, alreadyPresent: true };
+    }
     const shimsDir = overrides?.shimsDir || getShimsDir();
     const { rcFile, rcPath, shell } = getShellRcFile(overrides);
     // Read current rc file content

package/dist/lib/staleness/detectors/hooks.js

@@ -3,8 +3,8 @@
  * whose contents match the central source. Mirrors versions.ts:391-421.
  */
 import * as fs from 'fs';
-import * as path from 'path';
 import { agentConfigDirName } from '../../agents.js';
+import * as path from 'path';
 import { capableAgents } from '../../capabilities.js';
 import { resolveHookSource } from '../writers/sources.js';
 import { lazyAgentMap } from '../writers/lazy-map.js';

package/dist/lib/staleness/writers/hooks.js

@@ -5,8 +5,8 @@
  * stays in the orchestrator since it depends on the broader available set.
  */
 import * as fs from 'fs';
-import * as path from 'path';
 import { agentConfigDirName } from '../../agents.js';
+import * as path from 'path';
 import { capableAgents } from '../../capabilities.js';
 import { safeJoin } from '../../paths.js';
 import { registerHooksToSettings } from '../../hooks.js';

package/dist/lib/teams/agents.js

@@ -14,6 +14,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { randomUUID } from 'crypto';
 import { resolveAgentsDir } from './persistence.js';
+import { findExecutable } from '../platform/index.js';
 import { normalizeEvents } from './parsers.js';
 import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
@@ -300,13 +301,10 @@ export function checkCliAvailable(agentType) {
     if (!executable) {
         return [false, `Unknown agent type: ${agentType}`];
     }
-    try {
-        const whichPath = execFileSync('which', [executable], { encoding: 'utf-8' }).trim();
-        return [true, whichPath];
-    }
-    catch {
-        return [false, `CLI tool '${executable}' not found in PATH. Install it first.`];
-    }
+    const resolved = findExecutable(executable);
+    return resolved
+        ? [true, resolved]
+        : [false, `CLI tool '${executable}' not found in PATH. Install it first.`];
 }
 /** Check availability of all known agent CLIs. Returns a map of agent type to install status. */
 export function checkAllClis() {

package/dist/lib/teams/api.d.ts

@@ -64,6 +64,73 @@ export interface TaskStatusResult {
     };
     cursor: string;
 }
+/**
+ * Compact per-teammate snapshot for the default `teams status` view.
+ *
+ * The detail shape (`AgentStatusDetail`) carries the full prompt (often many
+ * KB), every absolute path the agent has touched, and uncapped message
+ * bodies. That's the right shape for programmatic consumers, but it makes
+ * `teams status` unreadable for orchestrators who only need: what state are
+ * you in, what did you just do, what files have you touched.
+ *
+ * Use {@link toAgentStatusSummary} to derive this from a detail record.
+ */
+export interface AgentStatusSummary {
+    agent_id: string;
+    name: string | null;
+    agent_type: string;
+    status: string;
+    duration: string | null;
+    tool_count: number;
+    has_errors: boolean;
+    pr_url: string | null;
+    files: {
+        /** Count of files modified since the cursor (delta), plus basenames. */
+        modified: {
+            count: number;
+            names: string[];
+        };
+        created: {
+            count: number;
+            names: string[];
+        };
+        deleted: {
+            count: number;
+            names: string[];
+        };
+        /** Read is noisy (per-Read events fire constantly); only emit a count. */
+        read: {
+            count: number;
+        };
+    };
+    /** Already capped at 15 × 120 chars by the detail builder. */
+    bash_commands: string[];
+    /** Last 3 messages, each body trimmed to ~400 chars. */
+    last_messages: string[];
+    /** ISO timestamp — feed back via --since for delta polling. */
+    cursor: string;
+}
+/** Compact aggregated result; mirrors {@link TaskStatusResult} but agents[] is the summary shape. */
+export interface TaskStatusSummaryResult {
+    task_name: string;
+    agents: AgentStatusSummary[];
+    summary: {
+        pending: number;
+        running: number;
+        completed: number;
+        failed: number;
+        stopped: number;
+    };
+    cursor: string;
+}
+/**
+ * Project a full AgentStatusDetail down to a compact AgentStatusSummary.
+ * Drops `prompt` entirely (caller knows what they queued), folds file lists
+ * to basenames + counts, caps `last_messages` to 3 × {@link SUMMARY_MESSAGE_MAX_CHARS}.
+ */
+export declare function toAgentStatusSummary(detail: AgentStatusDetail): AgentStatusSummary;
+/** Project a full TaskStatusResult down to the compact summary shape. */
+export declare function toTaskStatusSummary(result: TaskStatusResult): TaskStatusSummaryResult;
 /** Result of stopping one or more teammates. */
 export interface StopResult {
     task_name: string;

package/dist/lib/teams/api.js

@@ -55,6 +55,84 @@ function recentToolCalls(events, max = 10) {
         timestamp: typeof event.timestamp === 'string' ? event.timestamp : null,
     }));
 }
+/** Max files to name per category in the summary. Counts are always exact. */
+const SUMMARY_MAX_FILE_NAMES = 6;
+/** Max messages in the summary. */
+const SUMMARY_MAX_MESSAGES = 3;
+/** Max chars per message body in the summary. */
+const SUMMARY_MESSAGE_MAX_CHARS = 400;
+/**
+ * Reduce a file path to just its basename for compact rendering. Keeps the
+ * orchestrator oriented ("you touched types.ts") without dumping the full
+ * absolute path every time. The full paths are still in `AgentStatusDetail`
+ * for the verbose path.
+ */
+function basenameOf(p) {
+    const ix = p.lastIndexOf('/');
+    return ix < 0 ? p : p.slice(ix + 1);
+}
+/**
+ * Trim long assistant messages to a fixed budget. We collapse leading
+ * whitespace so the budget covers actual content, not indent.
+ */
+function trimMessage(msg, max = SUMMARY_MESSAGE_MAX_CHARS) {
+    const s = msg.replace(/^\s+/, '');
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max - 1) + '…';
+}
+/** Pull at most `max` basenames out of a path list, preserving order. */
+function compactFileList(paths, max = SUMMARY_MAX_FILE_NAMES) {
+    const seen = new Set();
+    const names = [];
+    for (const p of paths) {
+        const base = basenameOf(p);
+        if (seen.has(base))
+            continue;
+        seen.add(base);
+        names.push(base);
+        if (names.length >= max)
+            break;
+    }
+    return { count: paths.length, names };
+}
+/**
+ * Project a full AgentStatusDetail down to a compact AgentStatusSummary.
+ * Drops `prompt` entirely (caller knows what they queued), folds file lists
+ * to basenames + counts, caps `last_messages` to 3 × {@link SUMMARY_MESSAGE_MAX_CHARS}.
+ */
+export function toAgentStatusSummary(detail) {
+    return {
+        agent_id: detail.agent_id,
+        name: detail.name ?? null,
+        agent_type: detail.agent_type,
+        status: detail.status,
+        duration: detail.duration,
+        tool_count: detail.tool_count,
+        has_errors: detail.has_errors,
+        pr_url: detail.pr_url ?? null,
+        files: {
+            modified: compactFileList(detail.files_modified),
+            created: compactFileList(detail.files_created),
+            deleted: compactFileList(detail.files_deleted),
+            read: { count: detail.files_read.length },
+        },
+        bash_commands: detail.bash_commands,
+        last_messages: detail.last_messages
+            .slice(-SUMMARY_MAX_MESSAGES)
+            .map((m) => trimMessage(m)),
+        cursor: detail.cursor,
+    };
+}
+/** Project a full TaskStatusResult down to the compact summary shape. */
+export function toTaskStatusSummary(result) {
+    return {
+        task_name: result.task_name,
+        agents: result.agents.map(toAgentStatusSummary),
+        summary: result.summary,
+        cursor: result.cursor,
+    };
+}
 /** Spawn a new teammate in a task and return its initial metadata. */
 export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null) {
     const defaultMode = manager.getDefaultMode();

package/dist/lib/types.d.ts

@@ -9,6 +9,19 @@
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok' | 'kimi';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
+/** Per-agent run strategy config. */
+export interface AgentRunConfig {
+    strategy?: RunStrategy;
+}
+/** Default launch options applied by `agents run` when flags are omitted. */
+export interface RunDefaults {
+    mode?: Mode;
+    model?: string;
+}
+/** `run:` section in agents.yaml. Agent keys keep strategy; `defaults` stores selector rules. */
+export type RunConfig = Partial<Record<AgentId, AgentRunConfig>> & {
+    defaults?: Record<string, RunDefaults>;
+};
 /** Preview features that users can opt into via `agents beta`. */
 export type BetaFeatureName = 'drive' | 'factory';
 /** Subset of chalk color names used for agent-specific terminal output. */
@@ -196,9 +209,7 @@ export interface InstalledHook {
 /** Package manifest (agents.yaml) found inside a cloned config repo or package. */
 export interface Manifest {
     agents?: Partial<Record<AgentId, string>>;
-    run?: Partial<Record<AgentId, {
-        strategy?: RunStrategy;
-    }>>;
+    run?: RunConfig;
     beta?: {
         enabled?: BetaFeatureName[];
     };
@@ -504,9 +515,7 @@ export interface ExtraRepoConfig {
 /** Top-level structure of ~/.agents/.system/agents.yaml -- the CLI's persistent state. */
 export interface Meta {
     agents?: Partial<Record<AgentId, string>>;
-    run?: Partial<Record<AgentId, {
-        strategy?: RunStrategy;
-    }>>;
+    run?: RunConfig;
     beta?: {
         enabled?: BetaFeatureName[];
     };

package/dist/lib/versions.js

@@ -25,7 +25,7 @@ import { checkbox, select } from '@inquirer/prompts';
 import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset } from './state.js';
 import { defaultPatterns, expandPatterns } from './resource-patterns.js';
 import { listResources } from './resources.js';
-import { AGENTS, getAccountEmail, resolveAgentName, formatAgentError } from './agents.js';
+import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError } from './agents.js';
 import { discoverPermissionGroups, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.js';
 import { parseMcpServerConfig } from './mcp.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
@@ -1160,7 +1160,7 @@ export function removeVersion(agent, version) {
     // Clean up dangling config symlink if it pointed to the removed version
     const symlinkVersion = getConfigSymlinkVersion(agent);
     if (symlinkVersion === version) {
-        const configPath = path.join(os.homedir(), `.${agent}`);
+        const configPath = path.join(os.homedir(), agentConfigDirName(agent));
         try {
             fs.unlinkSync(configPath);
         }
@@ -1351,7 +1351,7 @@ async function getCliVersionFromPath(agent) {
 export function getResourceDiff(agent, version) {
     const agentConfig = AGENTS[agent];
     const versionHome = getVersionHomePath(agent, version);
-    const agentDir = path.join(versionHome, `.${agent}`);
+    const agentDir = path.join(versionHome, agentConfigDirName(agent));
     const diff = {
         commands: { added: [], dangling: [] },
         skills: { added: [], dangling: [] },
@@ -1500,7 +1500,7 @@ export function getResourceDiff(agent, version) {
 export function syncResourcesToVersion(agent, version, selection, options = {}) {
     const agentConfig = AGENTS[agent];
     const versionHome = getVersionHomePath(agent, version);
-    const agentDir = path.join(versionHome, `.${agent}`);
+    const agentDir = path.join(versionHome, agentConfigDirName(agent));
     fs.mkdirSync(agentDir, { recursive: true });
     // Capture whether the caller passed a selection. The pattern-expansion
     // path below reassigns `selection`, but for manifest write semantics we