@phnx-labs/agents-cli 1.20.0 → 1.20.4

package/dist/lib/hooks/profile.js

@@ -0,0 +1,129 @@
+/**
+ * Hook profiling — reads `hook.fire` events from the daily JSONL logs that
+ * generated shims (see `cache.ts`) emit on every invocation, and aggregates
+ * per-hook timing + cache stats.
+ *
+ * Only hooks declared with `cache:` get instrumented today, because only those
+ * are wrapped by a generated shim. Hooks without `cache:` are not in the
+ * profile output — that's deliberate: opting into the primitive is what
+ * surfaces the data.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getLogsDir } from '../state.js';
+/**
+ * Load every `hook.fire` event from the last `days` daily log files.
+ * Lines that aren't JSON or aren't `hook.fire` events are silently skipped —
+ * the events log is multiplexed (version.switch, secrets.get, …).
+ */
+export function loadHookFireEvents(days = 7, logsDir = getLogsDir()) {
+    if (!fs.existsSync(logsDir))
+        return [];
+    const today = new Date();
+    const events = [];
+    for (let i = 0; i < days; i++) {
+        const d = new Date(today);
+        d.setUTCDate(d.getUTCDate() - i);
+        const yyyy = d.getUTCFullYear();
+        const mm = String(d.getUTCMonth() + 1).padStart(2, '0');
+        const dd = String(d.getUTCDate()).padStart(2, '0');
+        const file = path.join(logsDir, `events-${yyyy}-${mm}-${dd}.jsonl`);
+        if (!fs.existsSync(file))
+            continue;
+        const raw = fs.readFileSync(file, 'utf-8');
+        for (const line of raw.split('\n')) {
+            if (!line)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (parsed.event !== 'hook.fire')
+                continue;
+            if (typeof parsed.hook !== 'string')
+                continue;
+            if (typeof parsed.ms !== 'number')
+                continue;
+            events.push(parsed);
+        }
+    }
+    return events;
+}
+/** Percentile of a sorted-ascending array. p in [0,100]. Linear interpolation. */
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    if (sorted.length === 1)
+        return sorted[0];
+    const rank = (p / 100) * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo];
+    const frac = rank - lo;
+    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
+}
+/** Aggregate fire events into a per-hook profile, sorted by p99 desc. */
+export function aggregateHookProfile(events) {
+    const byHook = new Map();
+    for (const e of events) {
+        if (!e.hook)
+            continue;
+        if (!byHook.has(e.hook))
+            byHook.set(e.hook, []);
+        byHook.get(e.hook).push(e);
+    }
+    const rows = [];
+    for (const [hook, evs] of byHook) {
+        const sortedMs = evs.map(e => e.ms).sort((a, b) => a - b);
+        const n = evs.length;
+        const sum = sortedMs.reduce((a, b) => a + b, 0);
+        const hits = evs.filter(e => e.cache === 'hit').length;
+        const stale = evs.filter(e => e.cache === 'stale-prefetch').length;
+        const misses = evs.filter(e => e.cache === 'miss').length;
+        const errors = evs.filter(e => typeof e.exit === 'number' && e.exit !== 0).length;
+        rows.push({
+            hook,
+            n,
+            p50Ms: Math.round(percentile(sortedMs, 50)),
+            p99Ms: Math.round(percentile(sortedMs, 99)),
+            meanMs: Math.round(sum / n),
+            maxMs: sortedMs[sortedMs.length - 1],
+            cacheHitPct: Math.round((hits / n) * 100),
+            cacheStalePct: Math.round((stale / n) * 100),
+            cacheMissPct: Math.round((misses / n) * 100),
+            errorCount: errors,
+        });
+    }
+    rows.sort((a, b) => b.p99Ms - a.p99Ms);
+    return rows;
+}
+/** Human-friendly duration: "42ms" / "1.2s" / "12s" / "2m". */
+export function formatMs(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 10_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    if (ms < 60_000)
+        return `${Math.round(ms / 1000)}s`;
+    const mins = Math.floor(ms / 60_000);
+    const secs = Math.round((ms % 60_000) / 1000);
+    return secs > 0 ? `${mins}m${secs}s` : `${mins}m`;
+}
+/** Format a row's cache column: `hit:97% miss:3%` or `n/a` when nothing cached. */
+export function formatCacheColumn(row) {
+    if (row.cacheHitPct + row.cacheStalePct + row.cacheMissPct === 0)
+        return 'n/a';
+    const parts = [];
+    if (row.cacheHitPct > 0)
+        parts.push(`hit:${row.cacheHitPct}%`);
+    if (row.cacheStalePct > 0)
+        parts.push(`stale:${row.cacheStalePct}%`);
+    if (row.cacheMissPct > 0)
+        parts.push(`miss:${row.cacheMissPct}%`);
+    return parts.join(' ');
+}
+export const DEFAULT_SLOW_HOOK_WARN_MS = 2000;

package/dist/lib/hooks.d.ts

@@ -124,16 +124,6 @@ export declare function listCentralHooks(): HookEntry[];
  * Hooks marked `enabled: false` are dropped from the returned map.
  */
 export declare function parseHookManifest(): Record<string, ManifestHook>;
-/**
- * Register hooks as lifecycle events in an agent's config.
- * Reads hooks.yaml manifest, merges into the agent's config file(s).
- * Only manages hooks whose command paths are under ~/.agents/hooks/ or
- * ~/.agents-system/hooks/. Does not remove user-added hooks.
- *
- * @param agentsDirOverride - When provided, treats this single dir as the
- *   only managed hook root. Used by tests to inject a temp path. In normal
- *   operation, both user and system roots are consulted with user precedence.
- */
 export declare function registerHooksToSettings(agentId: AgentId, versionHome: string, hookManifest?: Record<string, ManifestHook>, agentsDirOverride?: string): {
     registered: string[];
     errors: string[];

package/dist/lib/hooks.js

@@ -61,6 +61,29 @@ function isManagedHookCommand(command, prefixes) {
     return false;
 }
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
+import { generateHookShim, parseCacheConfig, removeHookShim } from './hooks/cache.js';
+import { getHookShimsDir } from './state.js';
+/**
+ * Resolve the command path to register for a hook.
+ *
+ * Returns either the raw script path (no `cache:` set, legacy behavior) or
+ * the path to a generated caching/timing shim. The shim is written as a
+ * side effect when `cache:` is configured. The agent-native settings file
+ * gets the same shape either way — just a different command path.
+ */
+function resolveHookCommand(name, hookDef, resolveScript) {
+    const scriptPath = resolveScript(hookDef.script);
+    if (!scriptPath)
+        return null;
+    const cache = parseCacheConfig(hookDef.cache);
+    if (!cache) {
+        // No caching opted in — make sure a previously generated shim from an
+        // earlier `cache:` config is gone so the JSONL doesn't keep claiming hits.
+        removeHookShim(name);
+        return scriptPath;
+    }
+    return generateHookShim({ name, scriptPath, cache });
+}
 /**
  * Extensions that are NEVER hooks — docs, configuration, plain data. A file
  * in hooks/ with one of these extensions is auxiliary content (e.g., the
@@ -646,11 +669,35 @@ const CODEX_MATCHER_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'SessionStart
  *   only managed hook root. Used by tests to inject a temp path. In normal
  *   operation, both user and system roots are consulted with user precedence.
  */
+/**
+ * Delete shim files for hooks that no longer exist in the manifest.
+ * managedPrefixes already GCs the settings.json entries pointing at orphaned
+ * shims, but the .sh files on disk would otherwise persist forever. Called
+ * once per registerHooksToSettings invocation — cheap (a single readdir).
+ */
+function sweepOrphanShims(manifest) {
+    const shimsDir = getHookShimsDir();
+    if (!fs.existsSync(shimsDir))
+        return;
+    const activeNames = new Set(Object.keys(manifest));
+    for (const file of fs.readdirSync(shimsDir)) {
+        if (!file.endsWith('.sh'))
+            continue;
+        const name = file.slice(0, -3);
+        if (activeNames.has(name))
+            continue;
+        try {
+            fs.unlinkSync(path.join(shimsDir, file));
+        }
+        catch { /* best effort */ }
+    }
+}
 export function registerHooksToSettings(agentId, versionHome, hookManifest, agentsDirOverride) {
     const manifest = hookManifest || parseHookManifest();
     if (Object.keys(manifest).length === 0) {
         return { registered: [], errors: [] };
     }
+    sweepOrphanShims(manifest);
     const overrideRoots = agentsDirOverride ? [agentsDirOverride] : null;
     // Scripts are copied into the version home during sync — prefer that stable
     // local path so registered commands don't break when source dirs change.
@@ -673,6 +720,10 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
         : [
             ...getManagedHookPrefixes(),
             ...(localHooksDir ? [localHooksDir + path.sep] : []),
+            // Generated cache/timing shims live here; needs GC coverage so that a
+            // hook whose `cache:` field is removed gets its stale shim path purged
+            // from the agent's settings file (see resolveHookCommand).
+            getHookShimsDir() + path.sep,
         ];
     if (agentId === 'claude') {
         return registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes);
@@ -737,12 +788,13 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
     }
     const hooks = config.hooks;
     // Build set of all command paths the current manifest will register.
-    // Used to garbage-collect stale entries left behind after hook renames.
+    // Used to garbage-collect stale entries left behind after hook renames
+    // or after a `cache:` field is added/removed (raw script vs shim path).
     const currentManifestPaths = new Set();
-    for (const hookDef of Object.values(manifest)) {
+    for (const [hookName, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
-        const resolved = resolveScript(hookDef.script);
+        const resolved = resolveHookCommand(hookName, hookDef, resolveScript);
         if (resolved)
             currentManifestPaths.add(resolved);
     }
@@ -766,7 +818,7 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
     for (const [name, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
-        const commandPath = resolveScript(hookDef.script);
+        const commandPath = resolveHookCommand(name, hookDef, resolveScript);
         if (!commandPath) {
             errors.push(`${name}: script not found in user or system hooks dir`);
             continue;
@@ -830,12 +882,13 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
             return { registered, errors };
         }
     }
-    // Build set of current manifest command paths for codex to GC stale entries
+    // Build set of current manifest command paths for codex to GC stale entries.
+    // Uses resolveHookCommand so cached hooks resolve to their shim path.
     const currentManifestPaths = new Set();
-    for (const hookDef of Object.values(manifest)) {
+    for (const [hookName, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
-        const resolved = resolveScript(hookDef.script);
+        const resolved = resolveHookCommand(hookName, hookDef, resolveScript);
         if (resolved)
             currentManifestPaths.add(resolved);
     }
@@ -853,7 +906,7 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
     for (const [name, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
-        const commandPath = resolveScript(hookDef.script);
+        const commandPath = resolveHookCommand(name, hookDef, resolveScript);
         if (!commandPath) {
             errors.push(`${name}: script not found in user or system hooks dir`);
             continue;
@@ -941,10 +994,10 @@ function registerHooksForGemini(versionHome, manifest, resolveScript, managedPre
             }
             const hooks = config.hooks;
             const currentManifestPaths = new Set();
-            for (const hookDef of Object.values(manifest)) {
+            for (const [hookName, hookDef] of Object.entries(manifest)) {
                 if (!hookDef.events || hookDef.events.length === 0)
                     continue;
-                const resolved = resolveScript(hookDef.script);
+                const resolved = resolveHookCommand(hookName, hookDef, resolveScript);
                 if (resolved)
                     currentManifestPaths.add(resolved);
             }
@@ -965,7 +1018,7 @@ function registerHooksForGemini(versionHome, manifest, resolveScript, managedPre
             for (const [name, hookDef] of Object.entries(manifest)) {
                 if (!hookDef.events || hookDef.events.length === 0)
                     continue;
-                const commandPath = resolveScript(hookDef.script);
+                const commandPath = resolveHookCommand(name, hookDef, resolveScript);
                 if (!commandPath) {
                     errors.push(`${name}: script not found in user or system hooks dir`);
                     continue;
@@ -1039,7 +1092,7 @@ function registerHooksForAntigravity(versionHome, manifest, resolveScript, manag
     // hooks. Only managed paths are considered for removal — user-added entries
     // outside managedPrefixes are preserved.
     const currentManifestPaths = new Set();
-    for (const hookDef of Object.values(manifest)) {
+    for (const [hookName, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
         // Only paths whose events map to a known agy event would actually be
@@ -1047,7 +1100,7 @@ function registerHooksForAntigravity(versionHome, manifest, resolveScript, manag
         const anyMapped = hookDef.events.some((e) => ANTIGRAVITY_EVENT_MAP[e]);
         if (!anyMapped)
             continue;
-        const resolved = resolveScript(hookDef.script);
+        const resolved = resolveHookCommand(hookName, hookDef, resolveScript);
         if (resolved)
             currentManifestPaths.add(resolved);
     }
@@ -1072,7 +1125,7 @@ function registerHooksForAntigravity(versionHome, manifest, resolveScript, manag
     for (const [name, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
-        const commandPath = resolveScript(hookDef.script);
+        const commandPath = resolveHookCommand(name, hookDef, resolveScript);
         if (!commandPath) {
             errors.push(`${name}: script not found in user or system hooks dir`);
             continue;
@@ -1128,7 +1181,7 @@ function registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefi
     for (const [name, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
-        const commandPath = resolveScript(hookDef.script);
+        const commandPath = resolveHookCommand(name, hookDef, resolveScript);
         if (!commandPath) {
             errors.push(`${name}: script not found`);
             continue;

package/dist/lib/import.d.ts

@@ -81,6 +81,27 @@ export interface AgentBinarySpec {
  *     node_modules/.bin/{cliCommand} -> {binaryEntry}
  */
 export declare function importAgentBinary(spec: AgentBinarySpec, version: string, globalPath: string, versionDir: string): ImportBinaryResult;
+/**
+ * Register an existing installScript-based binary (Grok, Antigravity, Cursor,
+ * etc. — anything with `npmPackage: ''` and a curl/brew installer) under the
+ * managed version path. Unlike `importAgentBinary` this skips the npm
+ * package.json walk and just symlinks the resolved PATH binary directly into
+ * `{versionDir}/node_modules/.bin/{cliCommand}`. The symlink is what makes
+ * `listInstalledVersions` consider the version Managed.
+ *
+ * Layout produced:
+ *
+ *   {versionDir}/
+ *     package.json                              # marker (private, imported, from)
+ *     home/                                     # empty isolated $HOME
+ *     node_modules/.bin/{cliCommand} -> {binaryPath}
+ *
+ * For agents whose binary lookup is special-cased elsewhere (e.g. Grok's
+ * `~/.grok/downloads/`), the symlink is still created — `getBinaryPath` won't
+ * read it for those agents, but it documents provenance and lets a future
+ * refactor consolidate the binary-resolution registry.
+ */
+export declare function importInstallScriptBinary(spec: AgentBinarySpec, version: string, binaryPath: string, versionDir: string): ImportBinaryResult;
 /**
  * Resolve the on-disk npm package directory for an agent's CLI binary by
  * walking up from the binary, following any symlinks. Returns null if the

package/dist/lib/import.js

@@ -17,6 +17,7 @@
  * true.
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { AGENTS } from './agents.js';
 import { getVersionsDir } from './state.js';
@@ -42,12 +43,17 @@ export async function importAgentConfig(agentId, version) {
     const configDir = agent.configDir;
     const versionsDir = getVersionsDir();
     const versionHome = path.join(versionsDir, agentId, version, 'home');
-    const versionConfigDir = path.join(versionHome, `.${agentId}`);
+    // Match the shim's derivation in generateShimScript: the per-version config
+    // path mirrors the original configDir's path relative to $HOME. Hardcoding
+    // `.${agentId}` broke for nested configDirs like Antigravity
+    // (`~/.gemini/antigravity-cli`) — the destination would be `.antigravity`,
+    // mismatching the shim's expectation of `.gemini/antigravity-cli`.
+    const versionConfigDir = path.join(versionHome, path.relative(os.homedir(), configDir));
     if (fs.existsSync(versionConfigDir)) {
         return { success: false, skipped: true, error: `${version} already installed` };
     }
     try {
-        fs.mkdirSync(versionHome, { recursive: true });
+        fs.mkdirSync(path.dirname(versionConfigDir), { recursive: true });
         fs.renameSync(configDir, versionConfigDir);
         fs.symlinkSync(versionConfigDir, configDir);
         setGlobalDefault(agentId, version);
@@ -155,6 +161,53 @@ export function importAgentBinary(spec, version, globalPath, versionDir) {
         return { success: false, error: err.message };
     }
 }
+/**
+ * Register an existing installScript-based binary (Grok, Antigravity, Cursor,
+ * etc. — anything with `npmPackage: ''` and a curl/brew installer) under the
+ * managed version path. Unlike `importAgentBinary` this skips the npm
+ * package.json walk and just symlinks the resolved PATH binary directly into
+ * `{versionDir}/node_modules/.bin/{cliCommand}`. The symlink is what makes
+ * `listInstalledVersions` consider the version Managed.
+ *
+ * Layout produced:
+ *
+ *   {versionDir}/
+ *     package.json                              # marker (private, imported, from)
+ *     home/                                     # empty isolated $HOME
+ *     node_modules/.bin/{cliCommand} -> {binaryPath}
+ *
+ * For agents whose binary lookup is special-cased elsewhere (e.g. Grok's
+ * `~/.grok/downloads/`), the symlink is still created — `getBinaryPath` won't
+ * read it for those agents, but it documents provenance and lets a future
+ * refactor consolidate the binary-resolution registry.
+ */
+export function importInstallScriptBinary(spec, version, binaryPath, versionDir) {
+    const binaryLink = path.join(versionDir, 'node_modules', '.bin', spec.cliCommand);
+    let alreadyExists = false;
+    try {
+        fs.lstatSync(binaryLink);
+        alreadyExists = true;
+    }
+    catch {
+        /* not present */
+    }
+    if (alreadyExists) {
+        return { success: false, skipped: true, error: `${version} already installed`, resolvedFromPath: binaryPath };
+    }
+    if (!fs.existsSync(binaryPath)) {
+        return { success: false, error: `Binary does not exist: ${binaryPath}` };
+    }
+    try {
+        fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
+        fs.mkdirSync(path.join(versionDir, 'node_modules', '.bin'), { recursive: true });
+        fs.writeFileSync(path.join(versionDir, 'package.json'), JSON.stringify({ name: `agents-${spec.agentId}-${version}`, version: '1.0.0', private: true, imported: true, from: binaryPath, installScriptBased: true }, null, 2));
+        fs.symlinkSync(binaryPath, binaryLink);
+        return { success: true, resolvedFromPath: binaryPath };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
 /**
  * Resolve the on-disk npm package directory for an agent's CLI binary by
  * walking up from the binary, following any symlinks. Returns null if the

package/dist/lib/mcp.d.ts

@@ -43,6 +43,21 @@ export declare function parseMcpServerConfig(filePath: string): McpYamlConfig |
  * List all MCP server configs from ~/.agents/mcp/.
  */
 export declare function listMcpServerConfigs(cwd?: string): InstalledMcpServer[];
+/**
+ * Scan a repository for MCP server YAML configs.
+ * Looks under <repoPath>/mcp/*.yaml — same on-disk layout as ~/.agents/mcp/.
+ */
+export declare function discoverMcpConfigsFromRepo(repoPath: string): InstalledMcpServer[];
+/**
+ * Install an MCP YAML config from a source file into ~/.agents/mcp/.
+ * Re-serializes via writeMcpServerConfig so the on-disk filename is
+ * deterministic (sanitized from the server name).
+ */
+export declare function installMcpConfigCentrally(sourcePath: string): {
+    success: boolean;
+    error?: string;
+    path?: string;
+};
 /**
  * Get MCP servers by name.
  * If names is provided, returns only those servers.

package/dist/lib/mcp.js

@@ -113,6 +113,46 @@ export function listMcpServerConfigs(cwd = process.cwd()) {
     }
     return Array.from(results.values());
 }
+/**
+ * Scan a repository for MCP server YAML configs.
+ * Looks under <repoPath>/mcp/*.yaml — same on-disk layout as ~/.agents/mcp/.
+ */
+export function discoverMcpConfigsFromRepo(repoPath) {
+    const dir = path.join(repoPath, 'mcp');
+    if (!fs.existsSync(dir))
+        return [];
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml'))
+            continue;
+        const filePath = path.join(dir, entry.name);
+        const config = parseMcpServerConfig(filePath);
+        if (config) {
+            results.push({ name: config.name, path: filePath, config, scope: 'user' });
+        }
+    }
+    return results;
+}
+/**
+ * Install an MCP YAML config from a source file into ~/.agents/mcp/.
+ * Re-serializes via writeMcpServerConfig so the on-disk filename is
+ * deterministic (sanitized from the server name).
+ */
+export function installMcpConfigCentrally(sourcePath) {
+    try {
+        const config = parseMcpServerConfig(sourcePath);
+        if (!config) {
+            return { success: false, error: `Invalid MCP config at ${sourcePath}` };
+        }
+        const written = writeMcpServerConfig(config);
+        return { success: true, path: written };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
 /**
  * Get MCP servers by name.
  * If names is provided, returns only those servers.

package/dist/lib/permissions.d.ts

@@ -97,6 +97,19 @@ export declare function removePermissionSet(name: string): {
  * Claude uses: { permissions: { allow: ["Bash(*)", "Read(**)"], deny: [] } }
  */
 export declare function convertToClaudeFormat(set: PermissionSet): ClaudePermissions;
+/**
+ * Convert canonical permission set to Gemini format.
+ * Gemini reads tool allow-lists from settings.json under `tools.allowed`.
+ * Bash permissions map to run_shell_command(prefix) — the prefix is extracted
+ * from the canonical "Bash(cmd:*)" pattern by stripping the trailing ":*".
+ * Blanket Bash grants map to bare "run_shell_command" (no prefix filter).
+ * Non-Bash tool patterns are skipped; Gemini uses different tool names.
+ */
+export declare function convertToGeminiFormat(set: PermissionSet): {
+    tools: {
+        allowed: string[];
+    };
+};
 /**
  * Convert canonical permission set to OpenCode format.
  * OpenCode uses: { permission: { bash: { "git *": "allow", "rm *": "deny" } } }

package/dist/lib/permissions.js

@@ -14,13 +14,14 @@ import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
 import { getPermissionsDir, getUserPermissionsDir, ensureAgentsDir } from './state.js';
 import { safeJoin } from './paths.js';
+import { updateGeminiSettings } from './gemini-settings.js';
 const HOME = os.homedir();
 /** Agents that support the permissions subsystem. */
 // antigravity: permissions in ~/.gemini/antigravity-cli/settings.json under
 // `permissions: { allow: [...], deny: [...] }`. Serializer is a follow-up.
 // grok: permissions via --allow/--deny CLI flags or [permission] block in
 // ~/.grok/config.toml. Serializer is a follow-up.
-export const PERMISSIONS_CAPABLE_AGENTS = ['claude', 'codex', 'opencode', 'antigravity', 'grok'];
+export const PERMISSIONS_CAPABLE_AGENTS = ['claude', 'codex', 'opencode', 'antigravity', 'grok', 'gemini'];
 /** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export const CODEX_RULES_FILENAME = 'agents-deny.rules';
 export function containsBroadGrants(rules) {
@@ -416,6 +417,35 @@ function parseCanonicalPattern(permission) {
 }
 /** Blanket-Bash canonical forms that mean "allow any bash command". */
 const BLANKET_BASH_FORMS = new Set(['Bash', 'Bash(*)', 'Bash(**)']);
+/**
+ * Convert canonical permission set to Gemini format.
+ * Gemini reads tool allow-lists from settings.json under `tools.allowed`.
+ * Bash permissions map to run_shell_command(prefix) — the prefix is extracted
+ * from the canonical "Bash(cmd:*)" pattern by stripping the trailing ":*".
+ * Blanket Bash grants map to bare "run_shell_command" (no prefix filter).
+ * Non-Bash tool patterns are skipped; Gemini uses different tool names.
+ */
+export function convertToGeminiFormat(set) {
+    const allowed = new Set();
+    for (const perm of set.allow) {
+        if (BLANKET_BASH_FORMS.has(perm)) {
+            allowed.add('run_shell_command');
+            continue;
+        }
+        const parsed = parseCanonicalPattern(perm);
+        if (!parsed || parsed.tool !== 'bash')
+            continue;
+        const colonIdx = parsed.pattern.lastIndexOf(':');
+        const prefix = colonIdx > 0 ? parsed.pattern.slice(0, colonIdx) : parsed.pattern;
+        if (prefix === '*' || prefix === '**') {
+            allowed.add('run_shell_command');
+        }
+        else {
+            allowed.add(`run_shell_command(${prefix})`);
+        }
+    }
+    return { tools: { allowed: Array.from(allowed) } };
+}
 /**
  * Convert canonical permission set to OpenCode format.
  * OpenCode uses: { permission: { bash: { "git *": "allow", "rm *": "deny" } } }
@@ -881,6 +911,26 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             }
             return { success: true };
         }
+        if (agentId === 'gemini') {
+            const geminiPerms = convertToGeminiFormat(set);
+            const settingsPath = path.join(versionHome, '.gemini', 'settings.json');
+            updateGeminiSettings(settingsPath, (settings) => {
+                // Remove stale permissions key written by earlier versions of this serializer.
+                delete settings.permissions;
+                const tools = (typeof settings.tools === 'object' && settings.tools !== null && !Array.isArray(settings.tools))
+                    ? settings.tools
+                    : {};
+                if (merge) {
+                    const existing = Array.isArray(tools.allowed) ? tools.allowed : [];
+                    tools.allowed = Array.from(new Set([...existing, ...geminiPerms.tools.allowed]));
+                }
+                else {
+                    tools.allowed = geminiPerms.tools.allowed;
+                }
+                settings.tools = tools;
+            });
+            return { success: true };
+        }
         return { success: false, error: `Agent '${agentId}' does not support permissions` };
     }
     catch (err) {

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

@@ -45,6 +45,16 @@ export declare function knownMarketplacesPath(agent: AgentId, versionHome: strin
 /**
  * Copy plugin source into marketplace install dir.
  * Source of truth remains ~/.agents/plugins/<name>/ — this is a per-version snapshot.
+ *
+ * Symlinks pointing OUTSIDE the plugin source root are dropped. They show up
+ * when plugin authors (legitimately) link prompt-side references to sibling
+ * codebases — e.g. the rush plugin's `app -> ../../../rush/app` for @app/...
+ * autocomplete in user prompts. Faithfully copying those symlinks pollutes
+ * the marketplace with gigabytes of node_modules / .next / brand-asset video
+ * that the consumer (Claude Code, OpenClaw) then walks during plugin
+ * discovery — which is the documented cause of multi-minute startup hangs.
+ *
+ * Internal symlinks (target stays inside the plugin root) are preserved.
  */
 export declare function copyPluginToMarketplace(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): string;
 /**