@phnx-labs/agents-cli 1.18.5 → 1.19.0

package/dist/lib/permissions.js

@@ -19,6 +19,41 @@ const HOME = os.homedir();
 export const PERMISSIONS_CAPABLE_AGENTS = ['claude', 'codex', 'opencode'];
 /** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export const CODEX_RULES_FILENAME = 'agents-deny.rules';
+export function containsBroadGrants(rules) {
+    const broad = [];
+    const reasons = new Set();
+    for (const perm of rules.allow) {
+        if (BLANKET_BASH_FORMS.has(perm)) {
+            broad.push(perm);
+            reasons.add('allows any bash command and maps Codex to approval_policy=never');
+            continue;
+        }
+        const parsed = parseCanonicalPattern(perm);
+        if (!parsed)
+            continue;
+        if (parsed.tool === 'bash' && (parsed.pattern === '*' || parsed.pattern === '**')) {
+            broad.push(perm);
+            reasons.add('allows any bash command and maps Codex to approval_policy=never');
+        }
+        else if (parsed.tool === 'bash' && parsed.pattern.startsWith('/') && parsed.pattern.includes('*')) {
+            broad.push(perm);
+            reasons.add('allows wildcard absolute bash paths');
+        }
+        else if ((parsed.tool === 'write' || parsed.tool === 'read') && (parsed.pattern === '*' || parsed.pattern === '**')) {
+            broad.push(perm);
+            reasons.add(`allows broad ${parsed.tool} filesystem access`);
+        }
+    }
+    for (const dir of rules.additionalDirectories || []) {
+        if (dir.startsWith('/') || dir.startsWith('~/') || dir === '~' || dir.split(/[\\/]/).includes('..')) {
+            broad.push(`additionalDirectories:${dir}`);
+            reasons.add('adds a broad or parent-traversing sandbox directory');
+        }
+    }
+    if (broad.length === 0)
+        return null;
+    return { broad, reason: Array.from(reasons).join('; ') };
+}
 /**
  * Convert canonical deny rules to Codex Starlark .rules format.
  * E.g. "Bash(git reset:*)" -> prefix_rule(pattern=["git", "reset"], decision="forbidden")

package/dist/lib/plugin-marketplace.d.ts

@@ -68,7 +68,9 @@ export declare function unregisterMarketplace(agent: AgentId, versionHome: strin
  * enabledPlugins["<plugin>@agents-cli"]: true. Reads, mutates, writes —
  * preserving every other key.
  */
-export declare function enablePluginInSettings(pluginName: string, agent: AgentId, versionHome: string): void;
+export declare function enablePluginInSettings(pluginName: string, agent: AgentId, versionHome: string, options?: {
+    allowExecSurfaces?: boolean;
+}): void;
 /**
  * Remove the enabledPlugins key for this plugin. Inverse of enablePluginInSettings.
  */

package/dist/lib/plugin-marketplace.js

@@ -151,7 +151,10 @@ export function unregisterMarketplace(agent, versionHome) {
  * enabledPlugins["<plugin>@agents-cli"]: true. Reads, mutates, writes —
  * preserving every other key.
  */
-export function enablePluginInSettings(pluginName, agent, versionHome) {
+export function enablePluginInSettings(pluginName, agent, versionHome, options = {}) {
+    if (!options.allowExecSurfaces && marketplacePluginHasExecSurfaces(pluginName, agent, versionHome)) {
+        return;
+    }
     const sPath = settingsPath(agent, versionHome);
     let settings = {};
     if (fs.existsSync(sPath)) {
@@ -173,6 +176,38 @@ export function enablePluginInSettings(pluginName, agent, versionHome) {
     fs.mkdirSync(path.dirname(sPath), { recursive: true });
     fs.writeFileSync(sPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
 }
+function marketplacePluginHasExecSurfaces(pluginName, agent, versionHome) {
+    const root = path.join(marketplaceRoot(agent, versionHome), 'plugins', pluginName);
+    if (fs.existsSync(path.join(root, '.mcp.json')))
+        return true;
+    for (const dir of ['bin', 'scripts', 'permissions']) {
+        if (fs.existsSync(path.join(root, dir)))
+            return true;
+    }
+    const hooksFile = path.join(root, 'hooks', 'hooks.json');
+    if (fs.existsSync(hooksFile))
+        return true;
+    const hooksDir = path.join(root, 'hooks');
+    if (fs.existsSync(hooksDir)) {
+        try {
+            if (fs.readdirSync(hooksDir).some((entry) => !entry.startsWith('.')))
+                return true;
+        }
+        catch {
+            return true;
+        }
+    }
+    const settingsFile = path.join(root, 'settings.json');
+    if (!fs.existsSync(settingsFile))
+        return false;
+    try {
+        const settings = JSON.parse(fs.readFileSync(settingsFile, 'utf-8'));
+        return Object.keys(settings).some((key) => key !== 'permissions') || 'permissions' in settings;
+    }
+    catch {
+        return true;
+    }
+}
 /**
  * Remove the enabledPlugins key for this plugin. Inverse of enablePluginInSettings.
  */

package/dist/lib/plugins.d.ts

@@ -9,16 +9,30 @@
  * contents into agent version homes.
  */
 import type { AgentId, DiscoveredPlugin, PluginManifest } from './types.js';
+export interface PluginCapabilities {
+    hasHooks: boolean;
+    hasMcp: boolean;
+    hasBin: boolean;
+    hasScripts: boolean;
+    hasSettings: boolean;
+    hasPermissions: boolean;
+}
+export declare const PLUGIN_EXEC_SURFACE_LABELS: Record<keyof PluginCapabilities, string>;
 /**
  * Discover all plugins in ~/.agents/plugins/.
  * A valid plugin has a .claude-plugin/plugin.json manifest.
  */
 export declare function discoverPlugins(): DiscoveredPlugin[];
 export declare function buildDiscoveredPlugin(pluginRoot: string, manifest: PluginManifest): DiscoveredPlugin;
+export declare function inspectPluginCapabilities(pluginRoot: string): PluginCapabilities;
+export declare function hasPluginExecSurfaces(capabilities: PluginCapabilities): boolean;
+export declare function pluginCapabilityLabels(capabilities: PluginCapabilities): string[];
 /**
  * Load a plugin manifest from a plugin directory.
  */
 export declare function loadPluginManifest(pluginRoot: string): PluginManifest | null;
+export declare function validatePluginName(name: string): boolean;
+export declare function assertPluginTargetContained(targetRoot: string, pluginsDir: string): void;
 /**
  * Get a specific plugin by name.
  */
@@ -79,7 +93,10 @@ export declare function checkPluginDependencies(manifest: PluginManifest): strin
  * native install path and is marked enabled — see
  * https://code.claude.com/docs/en/plugins.
  */
-export declare function syncPluginToVersion(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): {
+export declare function syncPluginToVersion(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string, options?: {
+    allowExecSurfaces?: boolean;
+    version?: string;
+}): {
     success: boolean;
     skills: string[];
     commands: string[];
@@ -152,6 +169,7 @@ export declare function installPlugin(spec: string): Promise<{
     name: string;
     root: string;
     isNew: boolean;
+    capabilities: PluginCapabilities;
 }>;
 /**
  * Update an installed plugin by re-pulling from its original source.

package/dist/lib/plugins.js

@@ -10,15 +10,24 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { getPluginsDir, getTrashPluginsDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { AGENTS, PLUGINS_CAPABLE_AGENTS } from './agents.js';
+import { shouldInstallCommandAsSkill, installCommandSkillToVersion } from './command-skills.js';
 import { copyPluginToMarketplace, syncMarketplaceManifest, registerMarketplace, unregisterMarketplace, enablePluginInSettings, disablePluginInSettings, removePluginFromMarketplace, marketplaceIsEmpty, removeEmptyMarketplaceDir, isInstalledInMarketplace, marketplaceRoot, } from './plugin-marketplace.js';
 const PLUGIN_MANIFEST_DIR = '.claude-plugin';
 const PLUGIN_MANIFEST_FILE = 'plugin.json';
 const USER_CONFIG_FILE = '.user-config.json';
 const SOURCE_FILE = '.source';
+export const PLUGIN_EXEC_SURFACE_LABELS = {
+    hasHooks: 'hooks/',
+    hasMcp: '.mcp.json',
+    hasBin: 'bin/',
+    hasScripts: 'scripts/',
+    hasSettings: 'settings.json',
+    hasPermissions: 'permissions/',
+};
 /**
  * Discover all plugins in ~/.agents/plugins/.
  * A valid plugin has a .claude-plugin/plugin.json manifest.
@@ -59,6 +68,26 @@ export function buildDiscoveredPlugin(pluginRoot, manifest) {
         hasSettings: pluginHasNonPermissionSettings(pluginRoot),
     };
 }
+export function inspectPluginCapabilities(pluginRoot) {
+    const manifest = loadPluginManifest(pluginRoot);
+    const plugin = manifest ? buildDiscoveredPlugin(pluginRoot, manifest) : null;
+    return {
+        hasHooks: (plugin?.hooks.length || 0) > 0 || pluginHasDirectoryEntries(pluginRoot, 'hooks'),
+        hasMcp: fs.existsSync(path.join(pluginRoot, '.mcp.json')),
+        hasBin: (plugin?.bin.length || 0) > 0,
+        hasScripts: (plugin?.scripts.length || 0) > 0,
+        hasSettings: pluginHasNonPermissionSettings(pluginRoot),
+        hasPermissions: pluginHasPermissionsPath(pluginRoot),
+    };
+}
+export function hasPluginExecSurfaces(capabilities) {
+    return Object.values(capabilities).some(Boolean);
+}
+export function pluginCapabilityLabels(capabilities) {
+    return Object.keys(PLUGIN_EXEC_SURFACE_LABELS)
+        .filter((key) => capabilities[key])
+        .map((key) => PLUGIN_EXEC_SURFACE_LABELS[key]);
+}
 /**
  * Load a plugin manifest from a plugin directory.
  */
@@ -72,7 +101,7 @@ export function loadPluginManifest(pluginRoot) {
         const parsed = JSON.parse(content);
         if (!parsed.name || !parsed.version)
             return null;
-        if (/[/\\]/.test(parsed.name) || parsed.name.includes('..') || parsed.name.includes('\0')) {
+        if (!validatePluginName(parsed.name)) {
             return null;
         }
         return parsed;
@@ -81,6 +110,20 @@ export function loadPluginManifest(pluginRoot) {
         return null;
     }
 }
+export function validatePluginName(name) {
+    return name.length > 0
+        && !/[/\\]/.test(name)
+        && !name.includes('..')
+        && !name.includes('\0');
+}
+export function assertPluginTargetContained(targetRoot, pluginsDir) {
+    const resolvedPluginsDir = path.resolve(pluginsDir);
+    const resolvedTargetRoot = path.resolve(targetRoot);
+    if (resolvedTargetRoot !== resolvedPluginsDir
+        && !resolvedTargetRoot.startsWith(`${resolvedPluginsDir}${path.sep}`)) {
+        throw new Error(`Plugin install target escapes plugins directory: ${targetRoot}`);
+    }
+}
 /**
  * Get a specific plugin by name.
  */
@@ -279,7 +322,7 @@ export function checkPluginDependencies(manifest) {
  * native install path and is marked enabled — see
  * https://code.claude.com/docs/en/plugins.
  */
-export function syncPluginToVersion(plugin, agent, versionHome) {
+export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
     const result = {
         success: false,
         skills: [],
@@ -302,10 +345,36 @@ export function syncPluginToVersion(plugin, agent, versionHome) {
     if (Object.keys(userConfig).length > 0) {
         expandUserConfigInDir(installDir, userConfig);
     }
+    // 2b. Write agent-native manifest dir alongside .claude-plugin/ when the agent
+    //     expects a different directory name (e.g. Codex uses .codex-plugin/).
+    const agentManifestDir = AGENTS[agent].pluginManifestDir;
+    if (agentManifestDir && agentManifestDir !== PLUGIN_MANIFEST_DIR) {
+        const srcManifest = path.join(installDir, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE);
+        if (fs.existsSync(srcManifest)) {
+            const destManifestDir = path.join(installDir, agentManifestDir);
+            fs.mkdirSync(destManifestDir, { recursive: true });
+            fs.copyFileSync(srcManifest, path.join(destManifestDir, PLUGIN_MANIFEST_FILE));
+        }
+    }
     // 3-5. Synthesize manifest, register marketplace, enable plugin.
     syncMarketplaceManifest(agent, versionHome);
     registerMarketplace(agent, versionHome);
-    enablePluginInSettings(plugin.name, agent, versionHome);
+    enablePluginInSettings(plugin.name, agent, versionHome, {
+        allowExecSurfaces: options.allowExecSurfaces === true,
+    });
+    // 5b. Convert plugin commands/ to skills for agents that dropped command support
+    //     (Codex >= 0.117.0). Skill name is prefixed with plugin name to avoid
+    //     collision with standalone command skills.
+    if (options.version && shouldInstallCommandAsSkill(agent, options.version) && plugin.commands.length > 0) {
+        const agentDir = path.join(versionHome, `.${AGENTS[agent].id}`);
+        const skillSourceDirs = [path.join(agentDir, 'skills')];
+        for (const cmd of plugin.commands) {
+            const srcPath = path.join(plugin.root, 'commands', `${cmd}.md`);
+            if (fs.existsSync(srcPath)) {
+                installCommandSkillToVersion(agentDir, `${plugin.name}-${cmd}`, srcPath, skillSourceDirs);
+            }
+        }
+    }
     // 6. Migrate legacy dual-dash flat layout from previous versions of agents-cli.
     migrateLegacyFlatLayout(plugin, agent, versionHome);
     // Populate the result shape for backward-compatible callers/reporting.
@@ -321,7 +390,13 @@ export function syncPluginToVersion(plugin, agent, versionHome) {
     return result;
 }
 function pluginHasPermissions(plugin) {
-    const settingsPath = path.join(plugin.root, 'settings.json');
+    return pluginHasPermissionsPath(plugin.root);
+}
+function pluginHasPermissionsPath(pluginRoot) {
+    const permissionsDir = path.join(pluginRoot, 'permissions');
+    if (fs.existsSync(permissionsDir))
+        return true;
+    const settingsPath = path.join(pluginRoot, 'settings.json');
     if (!fs.existsSync(settingsPath))
         return false;
     try {
@@ -332,6 +407,17 @@ function pluginHasPermissions(plugin) {
         return false;
     }
 }
+function pluginHasDirectoryEntries(pluginRoot, dirName) {
+    const dir = path.join(pluginRoot, dirName);
+    if (!fs.existsSync(dir))
+        return false;
+    try {
+        return fs.readdirSync(dir).some((entry) => !entry.startsWith('.'));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Walk a directory and replace ${user_config.*} placeholders in text files.
  * Leaves all other variables (${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}) alone.
@@ -846,7 +932,11 @@ export async function installPlugin(spec) {
             targetName = path.basename(resolvedSource).replace(/\.git$/, '');
         }
     }
+    if (!validatePluginName(targetName)) {
+        throw new Error(`Invalid plugin name: ${targetName}`);
+    }
     const targetRoot = path.join(pluginsDir, targetName);
+    assertPluginTargetContained(targetRoot, pluginsDir);
     const isNew = !fs.existsSync(targetRoot);
     if (isLocalPath) {
         // Copy local directory
@@ -860,7 +950,7 @@ export async function installPlugin(spec) {
         if (fs.existsSync(targetRoot)) {
             fs.rmSync(targetRoot, { recursive: true, force: true });
         }
-        execSync(`git clone --depth 1 ${JSON.stringify(resolvedSource)} ${JSON.stringify(targetRoot)}`, {
+        execFileSync('git', ['clone', '--depth', '1', resolvedSource, targetRoot], {
             stdio: 'pipe',
         });
     }
@@ -870,9 +960,10 @@ export async function installPlugin(spec) {
         fs.rmSync(targetRoot, { recursive: true, force: true });
         throw new Error(`Installed source has no valid .claude-plugin/plugin.json`);
     }
+    const capabilities = inspectPluginCapabilities(targetRoot);
     // Persist source for future updates
     fs.writeFileSync(path.join(targetRoot, SOURCE_FILE), JSON.stringify({ source, isGit: !isLocalPath }), 'utf-8');
-    return { name: manifest.name, root: targetRoot, isNew };
+    return { name: manifest.name, root: targetRoot, isNew, capabilities };
 }
 /**
  * Update an installed plugin by re-pulling from its original source.
@@ -896,7 +987,7 @@ export async function updatePlugin(name) {
     }
     try {
         if (sourceInfo.isGit) {
-            execSync(`git -C ${JSON.stringify(plugin.root)} pull --ff-only`, { stdio: 'pipe' });
+            execFileSync('git', ['-C', plugin.root, 'pull', '--ff-only'], { stdio: 'pipe' });
         }
         else {
             const resolvedSource = sourceInfo.source.replace(/^~/, process.env.HOME || '~');

package/dist/lib/redact.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Shared redaction helpers for text that may be exported or logged.
+ */
+export declare function redactSecrets(text: string): string;

package/dist/lib/redact.js

@@ -0,0 +1,18 @@
+/**
+ * Shared redaction helpers for text that may be exported or logged.
+ */
+const SECRET_PATTERNS = [
+    [/\bAKIA[0-9A-Z]{16}\b/g, '[REDACTED_AWS_KEY]'],
+    [/\bghp_[A-Za-z0-9]{36}\b/g, '[REDACTED_GITHUB_TOKEN]'],
+    [/\bsk-[A-Za-z0-9]{20,}\b/g, '[REDACTED_API_KEY]'],
+    [/\bnpm_[A-Za-z0-9]{36}\b/g, '[REDACTED_NPM_TOKEN]'],
+    [/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[REDACTED_JWT]'],
+    [/\b([A-Z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD)[A-Z0-9_]*)=("[^"]*"|'[^']*'|\S+)/gi, '$1=[REDACTED]'],
+];
+export function redactSecrets(text) {
+    let safe = text;
+    for (const [pattern, replacement] of SECRET_PATTERNS) {
+        safe = safe.replace(pattern, replacement);
+    }
+    return safe;
+}

package/dist/lib/registry.d.ts

@@ -6,6 +6,8 @@
  * with transport, runtime, and argument metadata.
  */
 import type { RegistryType, RegistryConfig, McpServerEntry, SkillEntry, RegistrySearchResult, ResolvedPackage } from './types.js';
+export declare function validatedNpmSpec(spec: string): string;
+export declare function validatedPyPISpec(spec: string): string;
 /** Get all registries of a given type, merging defaults with user overrides. */
 export declare function getRegistries(type: RegistryType): Record<string, RegistryConfig>;
 /** Get only the enabled registries of a given type. */

package/dist/lib/registry.js

@@ -8,6 +8,21 @@
 import * as fs from 'fs';
 import { DEFAULT_REGISTRIES } from './types.js';
 import { readMeta, writeMeta } from './state.js';
+const UNSAFE_PACKAGE_SPEC_CHARS = /[;&|`$\s\x00-\x1f\x7f]/;
+const NPM_SPEC_PATTERN = /^(@[a-z0-9][a-z0-9-_.]*\/)?[a-z0-9][a-z0-9-_.]*(@[A-Za-z0-9._+-]+)?$/;
+const PYPI_SPEC_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*(\[[A-Za-z0-9,_-]+\])?(==[A-Za-z0-9._-]+)?$/;
+export function validatedNpmSpec(spec) {
+    if (spec.length > 214 || UNSAFE_PACKAGE_SPEC_CHARS.test(spec) || !NPM_SPEC_PATTERN.test(spec)) {
+        throw new Error(`Invalid npm package spec: ${spec}`);
+    }
+    return spec;
+}
+export function validatedPyPISpec(spec) {
+    if (UNSAFE_PACKAGE_SPEC_CHARS.test(spec) || !PYPI_SPEC_PATTERN.test(spec)) {
+        throw new Error(`Invalid PyPI package spec: ${spec}`);
+    }
+    return spec;
+}
 /** Get all registries of a given type, merging defaults with user overrides. */
 export function getRegistries(type) {
     const meta = readMeta();

package/dist/lib/sandbox.js

@@ -11,7 +11,15 @@ import * as path from 'path';
 import * as os from 'os';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 import { getRoutinesDir } from './state.js';
-const REAL_HOME = os.homedir();
+function resolveRealHome() {
+    const home = os.homedir();
+    try {
+        return fs.realpathSync(home);
+    }
+    catch {
+        return home;
+    }
+}
 /** Environment variables forwarded from the parent process into the sandbox. */
 const ENV_ALLOWLIST = [
     'PATH',
@@ -93,8 +101,9 @@ export function cleanJobHome(name) {
 }
 /** Symlink allowed directories into the overlay HOME, skipping paths outside the real HOME. */
 export function symlinkAllowedDirs(overlayHome, dirs) {
+    const realHome = resolveRealHome();
     for (const dir of dirs) {
-        const expanded = dir.replace(/^~/, REAL_HOME);
+        const expanded = dir.replace(/^~/, realHome);
         // Resolve .. and symlinks to prevent path traversal outside HOME
         let realPath;
         try {
@@ -105,10 +114,10 @@ export function symlinkAllowedDirs(overlayHome, dirs) {
             // Directory doesn't exist yet — resolve .. components without following symlinks
             realPath = path.resolve(expanded);
         }
-        if (!realPath.startsWith(REAL_HOME + path.sep) && realPath !== REAL_HOME) {
+        if (!realPath.startsWith(realHome + path.sep) && realPath !== realHome) {
             continue;
         }
-        const relativePath = path.relative(REAL_HOME, realPath);
+        const relativePath = path.relative(realHome, realPath);
         const symlinkTarget = path.join(overlayHome, relativePath);
         const parentDir = path.dirname(symlinkTarget);
         fs.mkdirSync(parentDir, { recursive: true });
@@ -122,6 +131,7 @@ export function symlinkAllowedDirs(overlayHome, dirs) {
 }
 /** Generate a Claude settings.json in the overlay with scoped permissions from the job config. */
 export function generateClaudeConfig(overlayHome, config) {
+    const realHome = resolveRealHome();
     const claudeDir = path.join(overlayHome, '.claude');
     fs.mkdirSync(claudeDir, { recursive: true });
     const allowPermissions = [];
@@ -152,7 +162,7 @@ export function generateClaudeConfig(overlayHome, config) {
     // Scope filesystem tools to allowed dirs
     if (config.allow?.dirs) {
         for (const dir of config.allow.dirs) {
-            const resolved = dir.replace(/^~/, REAL_HOME);
+            const resolved = dir.replace(/^~/, realHome);
             // Read always granted for allowed dirs
             allowPermissions.push(`Read(${resolved}/**)`);
             if (config.mode === 'edit') {

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

@@ -40,9 +40,15 @@ export interface SecretsBundle {
     /** Optional per-var metadata, keyed by var name (parallel to `vars`). */
     meta?: Record<string, VarMeta>;
 }
+export interface LegacyBundleCandidate {
+    name: string;
+    file: string;
+    keys: string[];
+}
 export declare const RESERVED_ENV_NAMES: Set<string>;
 export declare function bundleToEnvPrefix(name: string): string;
 export declare function isReservedEnvName(key: string): boolean;
+export declare function isLoaderOrInterpreterEnv(name: string): boolean;
 /** Validate a bundle name against the allowed pattern. Throws on invalid input. */
 export declare function validateBundleName(name: string): void;
 export declare function validateEnvKey(key: string): void;
@@ -107,16 +113,5 @@ export declare function keychainItemsForBundle(bundle: SecretsBundle): Array<{
     item: string;
 }>;
 export declare function parseDotenv(content: string): Record<string, string>;
-/**
- * One-shot migration: move legacy YAML bundles into the keychain. Scans both
- * `~/.agents/secrets/` and `~/.agents-system/secrets/` — past versions of the
- * CLI sometimes wrote bundles into the system repo even though that's never
- * been a legitimate location. After migration the directories are removed so
- * the system repo never carries a `secrets/` subdir again.
- *
- * Idempotent: re-runs after the dirs are gone are no-ops. Called eagerly at
- * the top of every `agents secrets` subcommand. Skipped on the latency-
- * sensitive `agents run` path.
- */
-export declare function migrateLegacyBundles(): void;
+export declare function migrateLegacyBundles(confirmBundle: (candidate: LegacyBundleCandidate) => boolean | Promise<boolean>): Promise<number>;
 export type { SecretRef };

package/dist/lib/secrets/bundles.js

@@ -43,7 +43,24 @@ export function bundleToEnvPrefix(name) {
     return name.replace(/[-\.]/g, '_').toUpperCase();
 }
 export function isReservedEnvName(key) {
-    return RESERVED_ENV_NAMES.has(key);
+    return RESERVED_ENV_NAMES.has(key.toUpperCase());
+}
+export function isLoaderOrInterpreterEnv(name) {
+    const upper = name.toUpperCase();
+    return upper.startsWith('LD_') ||
+        upper.startsWith('DYLD_') ||
+        [
+            'NODE_OPTIONS',
+            'PYTHONPATH',
+            'PYTHONSTARTUP',
+            'BASH_ENV',
+            'ENV',
+            'PERL5OPT',
+            'RUBYOPT',
+            'PROMPT_COMMAND',
+            'IFS',
+            'CDPATH',
+        ].includes(upper);
 }
 /** Validate a bundle name against the allowed pattern. Throws on invalid input. */
 export function validateBundleName(name) {
@@ -55,6 +72,9 @@ export function validateEnvKey(key) {
     if (!ENV_KEY_PATTERN.test(key)) {
         throw new Error(`Invalid environment variable name '${key}'. Must match [A-Za-z_][A-Za-z0-9_]*.`);
     }
+    if (isLoaderOrInterpreterEnv(key) || isReservedEnvName(key)) {
+        throw new Error(`Env key "${key}" is reserved — cannot be used in a secrets bundle. Reserved keys include PATH, HOME, USER, and dynamic-loader/interpreter vars (LD_*, DYLD_*, NODE_OPTIONS, etc.).`);
+    }
 }
 /** Assert that `t` is one of the known SECRET_TYPES. Throws with the allowed list otherwise. */
 export function validateSecretType(t) {
@@ -396,18 +416,7 @@ export function parseDotenv(content) {
     }
     return out;
 }
-/**
- * One-shot migration: move legacy YAML bundles into the keychain. Scans both
- * `~/.agents/secrets/` and `~/.agents-system/secrets/` — past versions of the
- * CLI sometimes wrote bundles into the system repo even though that's never
- * been a legitimate location. After migration the directories are removed so
- * the system repo never carries a `secrets/` subdir again.
- *
- * Idempotent: re-runs after the dirs are gone are no-ops. Called eagerly at
- * the top of every `agents secrets` subcommand. Skipped on the latency-
- * sensitive `agents run` path.
- */
-export function migrateLegacyBundles() {
+export async function migrateLegacyBundles(confirmBundle) {
     const home = os.homedir();
     const dirs = [
         path.join(home, '.agents', 'secrets'),
@@ -426,26 +435,35 @@ export function migrateLegacyBundles() {
         for (const entry of ymls) {
             const file = path.join(dir, entry);
             const name = entry.replace(/\.(yml|yaml)$/, '');
+            let parsed;
             try {
                 validateBundleName(name);
                 const raw = fs.readFileSync(file, 'utf-8');
-                const parsed = yaml.parse(raw);
-                if (!parsed || typeof parsed !== 'object')
-                    continue;
-                const bundle = {
-                    name,
-                    description: parsed.description,
-                    allow_exec: Boolean(parsed.allow_exec),
-                    icloud_sync: Boolean(parsed.icloud_sync),
-                    vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
-                };
-                writeBundle(bundle);
-                fs.unlinkSync(file);
-                migrated++;
+                parsed = yaml.parse(raw);
             }
             catch {
                 // Leave malformed YAMLs in place so the user can inspect them.
+                continue;
+            }
+            if (!parsed || typeof parsed !== 'object')
+                continue;
+            const bundle = {
+                name,
+                description: parsed.description,
+                allow_exec: Boolean(parsed.allow_exec),
+                icloud_sync: Boolean(parsed.icloud_sync),
+                vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
+            };
+            const keys = Object.keys(bundle.vars);
+            for (const key of keys) {
+                validateEnvKey(key);
             }
+            const proceed = await confirmBundle({ name, file, keys });
+            if (!proceed)
+                continue;
+            writeBundle(bundle);
+            fs.unlinkSync(file);
+            migrated++;
         }
         try {
             if (fs.readdirSync(dir).length === 0)
@@ -453,7 +471,5 @@ export function migrateLegacyBundles() {
         }
         catch { /* not empty or already gone */ }
     }
-    if (migrated > 0) {
-        console.log(`Migrated ${migrated} legacy bundle${migrated === 1 ? '' : 's'} into keychain.`);
-    }
+    return migrated;
 }

package/dist/lib/secrets/index.js

@@ -78,9 +78,9 @@ export function setKeychainBackendForTest(b) {
     backend = b;
     return prev;
 }
-// Backend routing: non-sync items go through /usr/bin/security so they share
-// an ACL identity with items created by previous CLI versions (no prompts on
-// existing data). Sync items must go through the signed .app — only the .app
+// Backend routing: non-sync items go through /usr/bin/security with an empty
+// trusted-app ACL; existing items written by older versions retain their ACL.
+// Sync items must go through the signed .app — only the .app
 // holds the keychain-access-groups entitlement macOS requires for
 // kSecAttrSynchronizable. Enumeration also goes through the .app because the
 // security CLI doesn't expose listing by service prefix.
@@ -166,7 +166,7 @@ export function setKeychainToken(item, value, sync = false) {
     }
     // `security -i` keeps the value out of argv (and `ps`).
     const user = os.userInfo().username;
-    const cmd = `add-generic-password -a ${quoteForSecurityCli(user)} -s ${quoteForSecurityCli(item)} -w ${quoteForSecurityCli(value)} -U\n`;
+    const cmd = `add-generic-password -a ${quoteForSecurityCli(user)} -s ${quoteForSecurityCli(item)} -w ${quoteForSecurityCli(value)} -T ${quoteForSecurityCli('')} -U\n`;
     const result = spawnSync('security', ['-i'], {
         input: cmd,
         stdio: ['pipe', 'pipe', 'pipe'],

package/dist/lib/session/cloud.d.ts

@@ -10,6 +10,8 @@
  *   GET /api/v1/cloud-runs/:id/session.jsonl → raw captured jsonl
  */
 import type { SessionMeta } from './types.js';
+export declare function assertContained(candidate: string, rootDir: string): string;
+export declare function validateCloudExecutionId(executionId: string): string;
 /**
  * List cloud executions the user has captured sessions for. Includes
  * completed + needs_review + failed; an empty session_path means capture