@phnx-labs/agents-cli 1.20.11 → 1.20.13

package/dist/lib/picker.js

@@ -14,6 +14,86 @@
  */
 import { createPrompt, useState, useKeypress, useEffect, useMemo, usePagination, usePrefix, makeTheme, isEnterKey, isUpKey, isDownKey, isSpaceKey, Separator, } from '@inquirer/core';
 import chalk from 'chalk';
+import { stripVTControlCharacters } from 'node:util';
+const DEFAULT_TERMINAL_ROWS = 24;
+const DEFAULT_TERMINAL_WIDTH = 80;
+function terminalWidth() {
+    return Math.max(1, process.stdout.columns || DEFAULT_TERMINAL_WIDTH);
+}
+function terminalRows() {
+    return Math.max(1, process.stdout.rows || DEFAULT_TERMINAL_ROWS);
+}
+function renderedRows(text, width) {
+    const normalizedWidth = Math.max(1, width);
+    return text.split('\n').reduce((rows, line) => {
+        const visible = stripVTControlCharacters(line).length;
+        return rows + Math.max(1, Math.ceil(visible / normalizedWidth));
+    }, 0);
+}
+function truncateAnsiLine(line, maxVisibleWidth) {
+    if (maxVisibleWidth <= 0)
+        return '';
+    const targetWidth = Math.max(0, maxVisibleWidth - 1);
+    const ansiPattern = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\))/y;
+    let out = '';
+    let visible = 0;
+    for (let i = 0; i < line.length;) {
+        ansiPattern.lastIndex = i;
+        const ansi = ansiPattern.exec(line);
+        if (ansi) {
+            out += ansi[0];
+            i = ansiPattern.lastIndex;
+            continue;
+        }
+        const char = line[i];
+        if (visible >= targetWidth)
+            break;
+        out += char;
+        visible += 1;
+        i += char.length;
+    }
+    return out + '\x1b[0m' + chalk.gray('…');
+}
+function takePreviewRows(preview, rowBudget, width) {
+    const lines = preview.split('\n');
+    const out = [];
+    let used = 0;
+    for (const line of lines) {
+        const lineRows = renderedRows(line, width);
+        if (used + lineRows <= rowBudget) {
+            out.push(line);
+            used += lineRows;
+            continue;
+        }
+        const remainingRows = rowBudget - used;
+        if (remainingRows > 0) {
+            out.push(truncateAnsiLine(line, remainingRows * width));
+        }
+        break;
+    }
+    return out;
+}
+function previewTruncatedMarker(width) {
+    const full = '... preview truncated to fit terminal';
+    const short = '... truncated';
+    const text = full.length <= width ? full : short;
+    if (text.length <= width)
+        return chalk.gray(text);
+    return chalk.gray(text.slice(0, Math.max(0, width - 1)) + '…');
+}
+/** Clip a picker preview so the full prompt can fit in the terminal viewport. */
+export function limitPreviewHeight(preview, maxRows, width) {
+    const normalizedRows = Math.max(0, maxRows);
+    if (normalizedRows === 0)
+        return '';
+    if (renderedRows(preview, width) <= normalizedRows)
+        return preview;
+    if (normalizedRows === 1)
+        return previewTruncatedMarker(width);
+    const lines = takePreviewRows(preview, normalizedRows - 1, width);
+    lines.push(previewTruncatedMarker(width));
+    return lines.join('\n');
+}
 /** Show an interactive fuzzy-filter picker and return the selected item, or null on cancel. */
 export function itemPicker(config) {
     const prompt = createPrompt((cfg, done) => {
@@ -90,18 +170,28 @@ export function itemPicker(config) {
             pageSize: cfg.pageSize ?? 10,
             loop: false,
         });
+        const enter = cfg.enterHint ?? 'select';
+        const help = previewOpen
+            ? chalk.gray(`↑↓ navigate · space: close preview · ⏎ ${enter} · esc: cancel`)
+            : chalk.gray(`↑↓ navigate${hasPreview ? ' · space: preview' : ''} · ⏎ ${enter} · esc: cancel`);
         const parts = [header, page];
         if (results.length === 0) {
             parts.push(chalk.gray(`  ${cfg.emptyMessage ?? 'No matches.'}`));
         }
         if (previewOpen && selected && cfg.buildPreview) {
-            parts.push(chalk.gray('─'.repeat(Math.min(process.stdout.columns || 80, 80))));
-            parts.push(cfg.buildPreview(selected.value));
+            const width = terminalWidth();
+            const separator = chalk.gray('─'.repeat(Math.min(width, 80)));
+            const fixedRows = renderedRows(header, width) +
+                renderedRows(parts.slice(1).join('\n'), width) +
+                renderedRows(separator, width) +
+                renderedRows(help, width);
+            const availablePreviewRows = terminalRows() - fixedRows;
+            const preview = limitPreviewHeight(cfg.buildPreview(selected.value), availablePreviewRows, width);
+            if (preview) {
+                parts.push(separator);
+                parts.push(preview);
+            }
         }
-        const enter = cfg.enterHint ?? 'select';
-        const help = previewOpen
-            ? chalk.gray(`↑↓ navigate · space: close preview · ⏎ ${enter} · esc: cancel`)
-            : chalk.gray(`↑↓ navigate${hasPreview ? ' · space: preview' : ''} · ⏎ ${enter} · esc: cancel`);
         parts.push(help);
         return [header, parts.slice(1).join('\n')];
     });

package/dist/lib/platform/index.d.ts

@@ -19,3 +19,4 @@ export * from './paths.js';
 export * from './exec.js';
 export * from './process.js';
 export * from './ipc.js';
+export * from './winpath.js';

package/dist/lib/platform/index.js

@@ -19,3 +19,4 @@ export * from './paths.js';
 export * from './exec.js';
 export * from './process.js';
 export * from './ipc.js';
+export * from './winpath.js';

package/dist/lib/platform/winpath.d.ts

@@ -0,0 +1,35 @@
+export interface WinPathResult {
+    success: boolean;
+    /** True when `dir` was already the first PATH entry (no write performed). */
+    alreadyPresent?: boolean;
+    error?: string;
+}
+/**
+ * Prepend `dir` to the Windows User PATH. Idempotent: a no-op when `dir` is
+ * already first; moves it to the front when it exists but is positioned later
+ * (e.g. appended by an older install) so it overrides conflicting entries.
+ * `dir` is passed via an env var so it is never interpolated into the script
+ * text.
+ */
+export declare function prependToWindowsUserPath(dir: string): WinPathResult;
+/**
+ * The effective PowerShell execution policy (e.g. `Restricted`, `RemoteSigned`),
+ * or null if it can't be determined (PowerShell missing / errored).
+ */
+export declare function getEffectiveExecutionPolicy(): string | null;
+/**
+ * Whether a policy blocks running unsigned local `.ps1` scripts — which is what
+ * npm and agents-cli generate (`npm.ps1`, `agents.ps1`). Under these the bare
+ * `agents` / `npm` commands fail in PowerShell with a security error even when
+ * on PATH. Pure — testable on any host.
+ */
+export declare function blocksLocalScripts(policy: string | null): boolean;
+/**
+ * Resolve the npm global-bin directory (where the generated `agents` /
+ * `agents.cmd` launchers live, and where npm expects PATH to point) from the
+ * package entrypoint. On Windows npm places bin launchers directly in the
+ * prefix root, so the bin dir is the prefix itself.
+ *
+ * entry = `<prefix>/node_modules/@phnx-labs/agents-cli/dist/index.js` → `<prefix>`
+ */
+export declare function npmGlobalBinFromEntry(entryJsPath: string): string;

package/dist/lib/platform/winpath.js

@@ -0,0 +1,86 @@
+/**
+ * Windows User PATH + execution-policy primitives.
+ *
+ * The single place that mutates the Windows User PATH via the .NET environment
+ * API (which writes the registry AND broadcasts WM_SETTINGCHANGE — the correct
+ * analog of editing a shell rc file: no `setx` truncation, no manual step).
+ * Consumers: `shims.ts` (shims dir) and `scripts/postinstall.js` (npm global-bin
+ * dir, so the `agents` command itself resolves).
+ *
+ * Leaf module — imports only `child_process` and `path` so it is cheap to load
+ * from the npm lifecycle script without pulling the rest of the CLI.
+ */
+import { execFileSync } from 'child_process';
+import * as path from 'path';
+/**
+ * Prepend `dir` to the Windows User PATH. Idempotent: a no-op when `dir` is
+ * already first; moves it to the front when it exists but is positioned later
+ * (e.g. appended by an older install) so it overrides conflicting entries.
+ * `dir` is passed via an env var so it is never interpolated into the script
+ * text.
+ */
+export function prependToWindowsUserPath(dir) {
+    const script = [
+        '$d = $env:AGENTS_WINPATH_DIR',
+        "$u = [Environment]::GetEnvironmentVariable('Path','User')",
+        "if ($null -eq $u) { $u = '' }",
+        "$parts = @($u -split ';' | Where-Object { $_ -ne '' })",
+        // Already first — nothing to do
+        "if ($parts.Count -gt 0 -and $parts[0] -eq $d) { 'present' } else {",
+        // Remove any existing occurrence then prepend, matching POSIX `export PATH="${dir}:$PATH"`
+        "  $newParts = @($d) + @($parts | Where-Object { $_ -ne $d })",
+        "  [Environment]::SetEnvironmentVariable('Path', ($newParts -join ';'), 'User')",
+        "  'added'",
+        '}',
+    ].join('\n');
+    try {
+        const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+            encoding: 'utf-8',
+            env: { ...process.env, AGENTS_WINPATH_DIR: dir },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+        return { success: true, alreadyPresent: out.includes('present') };
+    }
+    catch (err) {
+        return { success: false, error: `Could not update the Windows user PATH: ${err.message}` };
+    }
+}
+/**
+ * The effective PowerShell execution policy (e.g. `Restricted`, `RemoteSigned`),
+ * or null if it can't be determined (PowerShell missing / errored).
+ */
+export function getEffectiveExecutionPolicy() {
+    try {
+        const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', 'Get-ExecutionPolicy'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a policy blocks running unsigned local `.ps1` scripts — which is what
+ * npm and agents-cli generate (`npm.ps1`, `agents.ps1`). Under these the bare
+ * `agents` / `npm` commands fail in PowerShell with a security error even when
+ * on PATH. Pure — testable on any host.
+ */
+export function blocksLocalScripts(policy) {
+    if (!policy)
+        return false;
+    const p = policy.trim().toLowerCase();
+    return p === 'restricted' || p === 'allsigned';
+}
+/**
+ * Resolve the npm global-bin directory (where the generated `agents` /
+ * `agents.cmd` launchers live, and where npm expects PATH to point) from the
+ * package entrypoint. On Windows npm places bin launchers directly in the
+ * prefix root, so the bin dir is the prefix itself.
+ *
+ * entry = `<prefix>/node_modules/@phnx-labs/agents-cli/dist/index.js` → `<prefix>`
+ */
+export function npmGlobalBinFromEntry(entryJsPath) {
+    return path.resolve(path.dirname(entryJsPath), '..', '..', '..', '..');
+}

package/dist/lib/plugins.d.ts

@@ -41,6 +41,20 @@ export declare function discoverPlugins(opts?: {
     cwd?: string;
 }): DiscoveredPlugin[];
 export declare function buildDiscoveredPlugin(pluginRoot: string, manifest: PluginManifest, spec?: MarketplaceSpec): DiscoveredPlugin;
+/** One category of resources a plugin packages, for display breakdowns. */
+export interface PluginResourceGroup {
+    /** Category key: 'skills' | 'commands' | 'subagents' | 'hooks' | 'mcp' | 'lsp' | 'monitors' | 'bin' | 'scripts' | 'settings'. */
+    label: string;
+    /** Display names — slash-prefixed for skills/commands (e.g. `/code:dispatch`), raw names otherwise. */
+    items: string[];
+}
+/**
+ * Ordered, non-empty resource groups a plugin packages. Single source of truth
+ * for the breakdown shown by the plugin picker, `agents inspect --plugins`, and
+ * its detail view. Empty categories are omitted; `settings` appears only when
+ * the plugin merges non-permission settings.
+ */
+export declare function pluginResourceGroups(plugin: DiscoveredPlugin): PluginResourceGroup[];
 export declare function inspectPluginCapabilities(pluginRoot: string): PluginCapabilities;
 export declare function hasPluginExecSurfaces(capabilities: PluginCapabilities): boolean;
 export declare function pluginCapabilityLabels(capabilities: PluginCapabilities): string[];

package/dist/lib/plugins.js

@@ -105,6 +105,29 @@ export function buildDiscoveredPlugin(pluginRoot, manifest, spec = { kind: 'user
         hasSettings: pluginHasNonPermissionSettings(pluginRoot),
     };
 }
+/**
+ * Ordered, non-empty resource groups a plugin packages. Single source of truth
+ * for the breakdown shown by the plugin picker, `agents inspect --plugins`, and
+ * its detail view. Empty categories are omitted; `settings` appears only when
+ * the plugin merges non-permission settings.
+ */
+export function pluginResourceGroups(plugin) {
+    const groups = [
+        { label: 'skills', items: plugin.skills.map((s) => `/${plugin.name}:${s}`) },
+        { label: 'commands', items: plugin.commands.map((c) => `/${plugin.name}:${c}`) },
+        { label: 'subagents', items: plugin.agentDefs },
+        { label: 'hooks', items: plugin.hooks },
+        { label: 'mcp', items: plugin.mcpServers },
+        { label: 'lsp', items: plugin.lspServers },
+        { label: 'monitors', items: plugin.monitors },
+        { label: 'bin', items: plugin.bin },
+        { label: 'scripts', items: plugin.scripts },
+    ];
+    const out = groups.filter((g) => g.items.length > 0);
+    if (plugin.hasSettings)
+        out.push({ label: 'settings', items: ['settings.json'] });
+    return out;
+}
 export function inspectPluginCapabilities(pluginRoot) {
     const manifest = loadPluginManifest(pluginRoot);
     const plugin = manifest ? buildDiscoveredPlugin(pluginRoot, manifest) : null;

package/dist/lib/project-launch.js

@@ -47,6 +47,7 @@ import * as path from 'path';
 import { supports } from './capabilities.js';
 import { getEnabledExtraRepos, getExtraPluginsDir, getPluginsDir, getProjectAgentsDir, getProjectPluginsDir, getSystemPluginsDir, } from './state.js';
 import { getVersionHomePath } from './versions.js';
+import { transformSubagentForClaude } from './subagents.js';
 import { compileRulesForProject } from './rules/compile.js';
 import { discoverPluginsInDir, hasPluginExecSurfaces, inspectPluginCapabilities } from './plugins.js';
 import { MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, addPluginToSettings, copyPluginToMarketplace, marketplaceNameFor, marketplaceRoot, pluginInstallDir, registerMarketplace, removePluginFromSettings, syncMarketplaceManifest, } from './plugin-marketplace.js';
@@ -114,10 +115,22 @@ function touchLaunchSentinel(agent, version, cwd) {
     }
 }
 const CLAUDE_MIRROR_PLANS = [
-    { srcSubdir: 'subagents', destSubdir: 'agents', entriesAreDirs: false },
-    { srcSubdir: 'commands', destSubdir: 'commands', entriesAreDirs: false },
-    { srcSubdir: 'skills', destSubdir: 'skills', entriesAreDirs: true },
+    { srcSubdir: 'subagents', destSubdir: 'agents', mode: 'subagent-write' },
+    { srcSubdir: 'commands', destSubdir: 'commands', mode: 'file-symlink' },
+    { srcSubdir: 'skills', destSubdir: 'skills', mode: 'dir-symlink' },
 ];
+/**
+ * Marker prepended-as-trailing-comment to every subagent file WE generate.
+ * It's an HTML comment — invisible to the markdown the agent reads — placed on
+ * the last line so it never disturbs the leading `---` frontmatter block.
+ *
+ * Ownership rule (the one don't-clobber decision for written, non-symlink
+ * files): we only overwrite a `.claude/agents/<name>.md` whose content carries
+ * this marker. A user-authored file (no marker) or a symlink at the dest is
+ * left untouched. A marker beats an mtime/sidecar sentinel because it travels
+ * with the file across copies and git, and needs no out-of-band state.
+ */
+const GENERATED_SUBAGENT_MARKER = '<!-- agents-cli:generated-subagent';
 function mirrorWorkspaceResources(cwd, agent) {
     // v1: claude-only. Other agents have workspace conventions we haven't
     // mapped (amp: ~/.config/amp; antigravity: ~/.gemini/antigravity-cli;
@@ -147,13 +160,20 @@ function mirrorWorkspaceResources(cwd, agent) {
             continue;
         const destDir = path.join(agentWorkspaceDir, plan.destSubdir);
         fs.mkdirSync(destDir, { recursive: true });
+        // Subagents flatten N source files into one written .md — not a symlink.
+        if (plan.mode === 'subagent-write') {
+            const r = writeProjectSubagents(srcDir, destDir, cwd);
+            links += r.links;
+            skipped.push(...r.skipped);
+            continue;
+        }
         const entries = fs.readdirSync(srcDir, { withFileTypes: true });
         for (const entry of entries) {
             if (entry.name.startsWith('.'))
                 continue;
-            if (plan.entriesAreDirs && !entry.isDirectory())
+            if (plan.mode === 'dir-symlink' && !entry.isDirectory())
                 continue;
-            if (!plan.entriesAreDirs && !entry.isFile() && !entry.isSymbolicLink())
+            if (plan.mode === 'file-symlink' && !entry.isFile() && !entry.isSymbolicLink())
                 continue;
             const srcPath = path.join(srcDir, entry.name);
             const destPath = path.join(destDir, entry.name);
@@ -167,6 +187,91 @@ function mirrorWorkspaceResources(cwd, agent) {
     }
     return { links, skipped };
 }
+/**
+ * Mirror project subagents into `<cwd>/.claude/agents/`. The canonical source
+ * shape is a DIRECTORY containing AGENT.md (e.g. `.agents/subagents/probe/AGENT.md`)
+ * — confirmed by the detector (versions.ts) and lister (subagents.ts). Each
+ * such directory is flattened via transformSubagentForClaude (the exact writer
+ * the version-home sync uses) into a single `<name>.md`, then written under an
+ * ownership marker so a re-launch refreshes our file but never clobbers a
+ * user-authored one.
+ *
+ * Returns the same {links, skipped} shape the symlink path reports, so the
+ * caller's accounting is uniform across resource kinds.
+ */
+function writeProjectSubagents(srcDir, destDir, cwd) {
+    let links = 0;
+    const skipped = [];
+    for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.'))
+            continue;
+        if (!entry.isDirectory())
+            continue;
+        const subagentDir = path.join(srcDir, entry.name);
+        if (!fs.existsSync(path.join(subagentDir, 'AGENT.md')))
+            continue;
+        const destPath = path.join(destDir, `${entry.name}.md`);
+        if (writeSubagentIfOwned(subagentDir, destPath)) {
+            links += 1;
+        }
+        else {
+            skipped.push(path.relative(cwd, destPath));
+        }
+    }
+    return { links, skipped };
+}
+/**
+ * Write a flattened subagent file at `destPath`, refusing to clobber user state.
+ *
+ *   - dest missing            → write fresh.
+ *   - dest is our generation  → overwrite (refresh; carries GENERATED_SUBAGENT_MARKER).
+ *   - dest is a symlink / any
+ *     non-regular file         → SKIP (user state we don't own).
+ *   - dest is a regular file
+ *     without our marker        → SKIP (hand-authored .claude/agents/<name>.md).
+ *
+ * Returns true when our file is present (written now or already current),
+ * false when we left a user-owned dest alone.
+ */
+function writeSubagentIfOwned(subagentDir, destPath) {
+    let existing = null;
+    let destLstat = null;
+    try {
+        destLstat = fs.lstatSync(destPath);
+    }
+    catch { /* missing — write fresh */ }
+    if (destLstat) {
+        if (!destLstat.isFile())
+            return false; // symlink/dir/etc. — user state
+        try {
+            existing = fs.readFileSync(destPath, 'utf-8');
+        }
+        catch {
+            return false;
+        }
+        if (!existing.includes(GENERATED_SUBAGENT_MARKER))
+            return false; // hand-authored
+    }
+    let body;
+    try {
+        body = transformSubagentForClaude(subagentDir);
+    }
+    catch {
+        return false; // malformed AGENT.md — don't write a broken file
+    }
+    const content = `${body}\n\n${GENERATED_SUBAGENT_MARKER} — edit .agents/subagents/${path.basename(subagentDir)}/ instead -->\n`;
+    // Skip-fast: identical content already on disk → no write (keeps mtime stable).
+    if (existing === content)
+        return true;
+    try {
+        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+        fs.writeFileSync(destPath, content);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
 /**
  * Create or refresh a symlink at `destPath` pointing at `srcPath`. Returns
  * true if we wrote (or already had) the link, false if we skipped because

package/dist/lib/registry.js

@@ -61,6 +61,13 @@ export function removeRegistry(type, name) {
     }
     return false;
 }
+/**
+ * Cap every registry network call. Without this a slow or unreachable registry
+ * hangs the calling command indefinitely (`agents add`, `agents mcp`, package
+ * resolution) — and makes CI flake when the registry is unreachable. On timeout
+ * the fetch aborts, callers fall back to their git/no-match path.
+ */
+const REGISTRY_FETCH_TIMEOUT_MS = 8000;
 async function fetchMcpRegistry(url, query, limit = 20, apiKey) {
     const params = new URLSearchParams();
     if (query)
@@ -73,7 +80,10 @@ async function fetchMcpRegistry(url, query, limit = 20, apiKey) {
     if (apiKey) {
         headers['Authorization'] = `Bearer ${apiKey}`;
     }
-    const response = await fetch(fullUrl, { headers });
+    const response = await fetch(fullUrl, {
+        headers,
+        signal: AbortSignal.timeout(REGISTRY_FETCH_TIMEOUT_MS),
+    });
     if (!response.ok) {
         throw new Error(`Registry request failed: ${response.status} ${response.statusText}`);
     }
@@ -191,7 +201,10 @@ async function fetchSkillIndex(url, apiKey) {
     const headers = { Accept: 'application/json' };
     if (apiKey)
         headers['Authorization'] = `Bearer ${apiKey}`;
-    const response = await fetch(url, { headers });
+    const response = await fetch(url, {
+        headers,
+        signal: AbortSignal.timeout(REGISTRY_FETCH_TIMEOUT_MS),
+    });
     if (!response.ok) {
         throw new Error(`Registry request failed: ${response.status} ${response.statusText}`);
     }

package/dist/lib/runner.js

@@ -22,6 +22,7 @@ const AGENT_COMMANDS = {
     codex: ['codex', 'exec', '--sandbox', 'workspace-write', '{prompt}', '--json'],
     gemini: ['gemini', '{prompt}', '--output-format', 'stream-json'],
     kimi: ['kimi', '--prompt', '{prompt}', '--output-format', 'stream-json'],
+    droid: ['droid', 'exec', '{prompt}', '-o', 'stream-json'],
 };
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export function buildJobCommand(config, resolvedPrompt) {
@@ -105,6 +106,19 @@ export function buildJobCommand(config, resolvedPrompt) {
         }
         appendModelAndReasoning(cmd, config);
     }
+    if (config.agent === 'droid') {
+        // droid exec defaults to read-only (plan). Escalate autonomy per mode.
+        if (mode === 'edit') {
+            cmd.push('--auto', 'low');
+        }
+        else if (mode === 'auto') {
+            cmd.push('--auto', 'high');
+        }
+        else if (mode === 'skip') {
+            cmd.push('--skip-permissions-unsafe');
+        }
+        appendModelAndReasoning(cmd, config);
+    }
     return cmd;
 }
 /**

package/dist/lib/sandbox.js

@@ -10,7 +10,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
-import { getRoutinesDir } from './state.js';
+import { getRoutinesDir, getUserAgentsDir } from './state.js';
 function resolveRealHome() {
     const home = os.homedir();
     try {
@@ -58,7 +58,10 @@ function tomlString(value) {
 }
 /** Build a restricted environment for a sandboxed process, setting HOME to the overlay. */
 export function buildSpawnEnv(overlayHome, extraEnv) {
-    const env = { HOME: overlayHome };
+    const env = {
+        HOME: overlayHome,
+        AGENTS_USER_DIR: getUserAgentsDir(),
+    };
     for (const key of ENV_ALLOWLIST) {
         if (process.env[key]) {
             env[key] = process.env[key];

package/dist/lib/settings-manifest.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Settings carry-forward between version homes.
+ *
+ * Every installed version gets an isolated `home/`, so user-authored
+ * preferences (settings.json, config.toml, keybindings, auth) written while
+ * running one version do not exist in a freshly installed one. Resources
+ * managed in ~/.agents/ (commands, skills, hooks, rules, MCP YAML, plugins,
+ * subagents) are synced into every version home by syncResourcesToVersion and
+ * are deliberately NOT listed here — copying them would fight that sync.
+ *
+ * The manifest below classifies the remaining per-agent files, and
+ * carryForwardSettings() fills gaps in a target version home from a source
+ * version home. It never overwrites a value the target already has: scalars
+ * keep the target's value, objects merge recursively, arrays union. That makes
+ * the operation idempotent and safe to run on every `agents add` / `agents use`.
+ */
+import type { AgentId } from './types.js';
+export interface CarryForwardResult {
+    /** Manifest rel paths that were created or updated in the target home. */
+    applied: string[];
+    /** Backup directory holding pre-merge copies of modified target files, if any. */
+    backupDir?: string;
+}
+/**
+ * Fill gaps in `target` from `source` without overwriting target values:
+ * missing keys are copied, plain objects recurse, and everything else —
+ * scalars AND arrays — keeps the target's value. Arrays deliberately do not
+ * union: other writers (factory sync, hooks registration) mutate array entries
+ * in place, so a union would keep re-appending stale pre-mutation copies from
+ * the source on every carry (e.g. a user hook duplicated after the system
+ * hooks were merged into it). Returns a new object.
+ */
+export declare function fillGaps(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Carry user settings forward from one version home into another. Both paths
+ * are version-home roots (the directory containing `.claude/` / `.codex/`).
+ * Only fills gaps — never overwrites target values — so it is idempotent.
+ */
+export declare function carryForwardSettings(agent: AgentId, fromHome: string, toHome: string): CarryForwardResult;