@phnx-labs/agents-cli 1.20.71 → 1.20.73

package/dist/lib/shims.js

@@ -17,6 +17,7 @@ import { IS_WINDOWS, prependToWindowsUserPath } from './platform/index.js';
 import { getShimsDir, getVersionsDir, getBackupsDir, getHistoryDir, ensureAgentsDir } from './state.js';
 export { getShimsDir };
 import { AGENTS, agentConfigDirName, readAuthAccountIdentity } from './agents.js';
+import { codexHomeShimBash } from './codex-home.js';
 /**
  * Files and directories to always skip during conflict detection and migration.
  * These are never user config that should be migrated.
@@ -261,12 +262,7 @@ if [ "\$(uname -s)" = "Linux" ] && [ -z "\${CLAUDE_CODE_OAUTH_TOKEN:-}" ] && [ -
 fi
 `
         : agent === 'codex'
-            ? `
-# Codex reads its config (approval_policy, sandbox_mode, MCP servers, rules)
-# from CODEX_HOME. Point it at the versioned home so permissions/rules
-# written by agents-cli actually take effect.
-export CODEX_HOME="$VERSION_DIR/home/${configDirName}"
-`
+            ? codexHomeShimBash(`$VERSION_DIR/home/${configDirName}`, `$AGENTS_USER_DIR/.codex-homes/$VERSION`)
             : agent === 'copilot'
                 ? `
 # GitHub Copilot CLI honors COPILOT_HOME to relocate its config and state
@@ -682,6 +678,75 @@ export function createShim(agent) {
     }
     return shimPath;
 }
+// ─── White-label brand shims ──────────────────────────────────────────────────
+// A brand shim is a PURE pass-through: unlike an agent shim (which resolves a
+// version and execs the agent binary) or an alias shim (which injects a fixed
+// subcommand), it forwards argv verbatim to the agents-cli entrypoint with
+// `AGENTS_BRAND` set, so `<brand> <any-verb>` behaves exactly like
+// `agents <any-verb>` but presents under the brand's name. See lib/brand.ts.
+const BRAND_SHIM_MARKER = '# Brand shim:';
+/** The POSIX pass-through shim for a brand. */
+export function generateBrandShim(name) {
+    const agentsBin = shellQuote(getAgentsBinForGeneratedShim());
+    return `#!/bin/sh
+# Auto-generated by agents-cli - do not edit
+${BRAND_SHIM_MARKER} ${name} -> agents-cli (white-label)
+AGENTS_BIN=${agentsBin}
+if [ -z "$AGENTS_BIN" ] || [ ! -x "$AGENTS_BIN" ]; then
+  echo "${name}: agents-cli entrypoint missing or not executable: $AGENTS_BIN" >&2
+  exit 127
+fi
+export AGENTS_BRAND=${name}
+exec "$AGENTS_BIN" "$@"
+`;
+}
+/** Write a brand's pass-through shim(s) onto PATH; returns the shim path. */
+export function createBrandShim(name) {
+    ensureAgentsDir();
+    const shimsDir = getShimsDir();
+    const shimPath = path.join(shimsDir, name);
+    const targets = shimTargetsFor(process.platform);
+    if (targets.bash) {
+        fs.writeFileSync(shimPath, generateBrandShim(name), { mode: 0o755 });
+    }
+    if (targets.cmd) {
+        writeWindowsBrandShim(shimPath + '.cmd', name);
+    }
+    return shimPath;
+}
+/** Windows `.cmd` pass-through: set AGENTS_BRAND then forward argv to the entrypoint. */
+function writeWindowsBrandShim(cmdPath, name) {
+    const indexJs = getAgentsBinForGeneratedShim();
+    const content = `@echo off\r\n` +
+        `rem Auto-generated by agents-cli - do not edit\r\n` +
+        `rem Brand shim: ${name}\r\n` +
+        `set AGENTS_BRAND=${name}\r\n` +
+        `node "${indexJs}" %*\r\n`;
+    fs.writeFileSync(cmdPath, content);
+}
+/** True when the file at the given path is an agents-cli brand shim. */
+export function isBrandShim(filePath) {
+    try {
+        const head = fs.readFileSync(filePath, 'utf-8').slice(0, 300);
+        return head.includes(BRAND_SHIM_MARKER) || head.includes('rem Brand shim:');
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove a brand's shim companions. Returns true if anything was removed. */
+export function removeBrandShim(name) {
+    const shimsDir = getShimsDir();
+    const shimPath = path.join(shimsDir, name);
+    let removed = false;
+    for (const p of [shimPath, shimPath + '.cmd']) {
+        if (fs.existsSync(p) && isBrandShim(p)) {
+            fs.unlinkSync(p);
+            removed = true;
+        }
+    }
+    return removed;
+}
 /**
  * Generate a Windows `.cmd` launcher that delegates to `agents __shim <spec>`.
  * `spec` is the agent's cliCommand for the default-version shim, or
@@ -785,6 +850,29 @@ function assertSafeVersion(version) {
         throw new Error(`Refusing to generate shim for unsafe version: ${JSON.stringify(version)}`);
     }
 }
+/**
+ * Agents whose config directory can be relocated by an environment variable
+ * (the per-agent `managedEnv` block in `generateVersionedAliasScript` below).
+ *
+ * Only these can be installed with `agents add --isolated`: the versioned alias
+ * points that env var at the copy's private home, so the copy never reads or
+ * writes the user's real `~/.<agent>`. Every other agent isolates ONLY by
+ * adopting `~/.<agent>` via a symlink — which an isolated install deliberately
+ * skips — so an isolated copy would silently fall back to (and mutate) the real
+ * config dir. For those agents `--isolated` is refused up front.
+ *
+ * KEEP IN SYNC with the `managedEnv` switch in `generateVersionedAliasScript`.
+ * The colocated test `shims.isolation-capability.test.ts` enforces this.
+ */
+export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'grok', 'kimi'];
+/**
+ * Whether an agent supports a clean `--isolated` install — i.e. its config
+ * location can be redirected by an env var so the isolated copy stays fully
+ * separate from the user's real `~/.<agent>`. See {@link CONFIG_ENV_ISOLATED_AGENTS}.
+ */
+export function supportsIsolatedInstall(agent) {
+    return CONFIG_ENV_ISOLATED_AGENTS.includes(agent);
+}
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
@@ -806,12 +894,7 @@ export CLAUDE_CONFIG_DIR="$HOME/.agents/.history/versions/${agent}/${version}/ho
 export DISABLE_AUTOUPDATER="\${DISABLE_AUTOUPDATER:-1}"
 `
         : agent === 'codex'
-            ? `
-# Codex reads its config (approval_policy, sandbox_mode, MCP servers, rules)
-# from CODEX_HOME. Point direct aliases at the versioned home so permissions
-# and rules written by agents-cli actually take effect.
-export CODEX_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
-`
+            ? codexHomeShimBash(`$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}`, `$HOME/.agents/.codex-homes/${version}`)
             : agent === 'copilot'
                 ? `
 # Copilot honors COPILOT_HOME to relocate ~/.copilot (settings, mcp-config.json,
@@ -1039,7 +1122,7 @@ export function versionedAliasExists(agent, version) {
  * Get the path to the agent's config directory in HOME.
  * e.g., ~/.claude for claude, ~/.codex for codex
  */
-function getAgentConfigPath(agent) {
+export function getAgentConfigPath(agent) {
     const agentConfig = AGENTS[agent];
     const home = process.env.AGENTS_REAL_HOME || os.homedir();
     return agentConfig.configDir.replace(os.homedir(), home);
@@ -1567,7 +1650,10 @@ export function getConfigSymlinkVersion(agent) {
         if (!stat.isSymbolicLink()) {
             return null;
         }
-        const target = fs.readlinkSync(configPath);
+        // Normalize separators so this matches on Windows too — readlinkSync there
+        // returns backslash paths, which the forward-slash-only regex never matched
+        // (misclassifying an owned symlink as foreign, e.g. in `agents uninstall`).
+        const target = fs.readlinkSync(configPath).replace(/\\/g, '/');
         // Extract version from path like ~/.agents/versions/claude/2.0.65/home/.claude
         const match = target.match(/versions\/[^/]+\/([^/]+)\/home/);
         return match ? match[1] : null;
@@ -2194,7 +2280,7 @@ function isShimPathCommandLine(line, shimsDir) {
     }
     return trimmed.startsWith('export PATH=') || trimmed.startsWith('fish_add_path ');
 }
-function stripShimPathLines(content, shimsDir) {
+export function stripShimPathLines(content, shimsDir) {
     const lines = content.split('\n');
     const kept = [];
     for (let i = 0; i < lines.length; i++) {
@@ -2342,6 +2428,24 @@ export function listAgentsWithInstalledVersions() {
         .map((entry) => entry.name)
         .filter((agent) => fs.readdirSync(path.join(versionsDir, agent), { withFileTypes: true }).some((entry) => entry.isDirectory()));
 }
+function isInstalledVersionIsolated(agent, version) {
+    return fs.existsSync(path.join(getVersionsDir(), agent, version, '.isolated'));
+}
+export function listAgentsWithNonIsolatedInstalledVersions() {
+    const versionsDir = getVersionsDir();
+    if (!fs.existsSync(versionsDir)) {
+        return [];
+    }
+    const entries = fs.readdirSync(versionsDir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isDirectory() && AGENTS[entry.name])
+        .map((entry) => entry.name)
+        .filter((agent) => {
+        const agentVersionsDir = path.join(versionsDir, agent);
+        return fs.readdirSync(agentVersionsDir, { withFileTypes: true })
+            .some((entry) => entry.isDirectory() && !isInstalledVersionIsolated(agent, entry.name));
+    });
+}
 /**
  * Create shims for all installed agents.
  */
@@ -2356,7 +2460,7 @@ function ensureAllShims() {
             const agent = entry.name;
             const agentVersionsDir = path.join(versionsDir, agent);
             const versions = fs.readdirSync(agentVersionsDir, { withFileTypes: true })
-                .filter((e) => e.isDirectory());
+                .filter((e) => e.isDirectory() && !isInstalledVersionIsolated(agent, e.name));
             if (versions.length > 0 && !shimExists(agent)) {
                 createShim(agent);
             }

package/dist/lib/ssh-exec.d.ts

@@ -89,6 +89,20 @@ export interface SshExecRawResult {
  * U+FFFD replacement char (which would desync a byte offset from the wire).
  */
 export declare function sshExecRaw(target: string, remoteCmd: string, opts?: SshExecOptions): SshExecRawResult;
+export interface SshExecRawStreamOptions extends SshExecOptions {
+    onStdout: (chunk: Buffer) => void;
+    onStderr?: (chunk: Buffer) => void;
+    signal?: AbortSignal;
+}
+/**
+ * Stream raw stdout from a long-lived remote command over ssh.
+ *
+ * Unlike {@link sshStream}, this does not inherit local stdio: callers receive
+ * byte-exact stdout chunks and decide how to account for them. That matters for
+ * offset-resumed log following where a UTF-8 decode boundary must not shift the
+ * byte cursor.
+ */
+export declare function sshExecRawStream(target: string, remoteCmd: string, opts: SshExecRawStreamOptions): Promise<Omit<SshExecRawResult, 'stdout'>>;
 /** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
 export declare function sshReachable(target: string, timeoutMs?: number): boolean;
 export interface SshStreamOptions {

package/dist/lib/ssh-exec.js

@@ -205,6 +205,63 @@ export function sshExecRaw(target, remoteCmd, opts = {}) {
         timedOut,
     };
 }
+/**
+ * Stream raw stdout from a long-lived remote command over ssh.
+ *
+ * Unlike {@link sshStream}, this does not inherit local stdio: callers receive
+ * byte-exact stdout chunks and decide how to account for them. That matters for
+ * offset-resumed log following where a UTF-8 decode boundary must not shift the
+ * byte cursor.
+ */
+export function sshExecRawStream(target, remoteCmd, opts) {
+    assertValidSshTarget(target);
+    const mux = opts.multiplex === false ? [] : controlOpts();
+    const args = [...sshConnectOpts(mux, opts.hostKeyOpts), ...(opts.extraSshArgs ?? []), target, remoteCmd];
+    return new Promise((resolve) => {
+        const child = spawn('ssh', args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        const stderr = [];
+        let settled = false;
+        let timedOut = false;
+        let aborted = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', abort);
+            resolve({ code, stderr: Buffer.concat(stderr), timedOut });
+        };
+        const abort = () => {
+            aborted = true;
+            child.kill('SIGTERM');
+        };
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+            }, opts.timeoutMs)
+            : null;
+        child.stdout.on('data', (chunk) => { opts.onStdout(chunk); });
+        child.stderr.on('data', (chunk) => {
+            stderr.push(chunk);
+            opts.onStderr?.(chunk);
+        });
+        child.stdin.on('error', () => { });
+        child.stdin.end(opts.input ?? '');
+        opts.signal?.addEventListener('abort', abort, { once: true });
+        child.on('error', (err) => {
+            stderr.push(Buffer.from(err.message));
+            finish(null);
+        });
+        child.on('close', (code) => {
+            finish(aborted ? null : code);
+        });
+    });
+}
 /** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
 export function sshReachable(target, timeoutMs = 10000) {
     return sshExec(target, 'true', { timeoutMs, multiplex: true }).code === 0;

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

@@ -8,6 +8,30 @@ import * as path from 'path';
 import { capableAgents } from '../../capabilities.js';
 import { resolveHookSource } from '../writers/sources.js';
 import { lazyAgentMap } from '../writers/lazy-map.js';
+function hookSourcesMatch(src, dest) {
+    const srcStat = fs.lstatSync(src);
+    if (srcStat.isSymbolicLink())
+        return false;
+    if (srcStat.isDirectory()) {
+        if (!fs.existsSync(dest) || !fs.lstatSync(dest).isDirectory())
+            return false;
+        const entries = fs.readdirSync(src, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            if (!hookSourcesMatch(srcPath, destPath))
+                return false;
+        }
+        return true;
+    }
+    if (!srcStat.isFile())
+        return false;
+    if (!fs.existsSync(dest) || !fs.lstatSync(dest).isFile())
+        return false;
+    return fs.readFileSync(src, 'utf-8') === fs.readFileSync(dest, 'utf-8');
+}
 function buildHooksDetector(agent) {
     return {
         kind: 'hooks',
@@ -26,7 +50,7 @@ function buildHooksDetector(agent) {
                     continue;
                 }
                 try {
-                    if (fs.readFileSync(src, 'utf-8') === fs.readFileSync(path.join(hooksDir, hook), 'utf-8')) {
+                    if (hookSourcesMatch(src, path.join(hooksDir, hook))) {
                         synced.push(hook);
                     }
                 }

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

@@ -288,6 +288,69 @@ function buildOpenClawDetector() {
         },
     };
 }
+function buildCopilotDetector() {
+    return {
+        kind: 'permissions',
+        agent: 'copilot',
+        list({ versionHome, cwd }) {
+            const configPath = path.join(versionHome, '.copilot', 'permissions-config.json');
+            if (!fs.existsSync(configPath))
+                return [];
+            try {
+                const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                const locations = config.locations && typeof config.locations === 'object' && !Array.isArray(config.locations)
+                    ? config.locations
+                    : {};
+                const location = locations[path.resolve(cwd)];
+                const hasApprovals = Array.isArray(location?.tool_approvals) && location.tool_approvals.length > 0;
+                const hasDirectories = Array.isArray(location?.allowed_directories) && location.allowed_directories.length > 0;
+                if (hasApprovals || hasDirectories)
+                    return discoverPermissionGroups().map(g => g.name);
+            }
+            catch { /* parse fail */ }
+            return [];
+        },
+    };
+}
+function buildForgeDetector() {
+    return {
+        kind: 'permissions',
+        agent: 'forge',
+        list({ versionHome }) {
+            const permissionsPath = path.join(versionHome, '.forge', 'permissions.yaml');
+            if (!fs.existsSync(permissionsPath))
+                return [];
+            try {
+                const config = yaml.parse(fs.readFileSync(permissionsPath, 'utf-8'));
+                if (config && Array.isArray(config.policies) && config.policies.length > 0) {
+                    return discoverPermissionGroups().map(g => g.name);
+                }
+            }
+            catch { /* parse fail */ }
+            return [];
+        },
+    };
+}
+function buildHermesDetector() {
+    return {
+        kind: 'permissions',
+        agent: 'hermes',
+        list({ versionHome }) {
+            const configPath = path.join(versionHome, '.hermes', 'config.yaml');
+            if (!fs.existsSync(configPath))
+                return [];
+            try {
+                const config = yaml.parse(fs.readFileSync(configPath, 'utf-8'));
+                const hasAllow = Array.isArray(config?.command_allowlist) && config.command_allowlist.length > 0;
+                const hasDeny = Array.isArray(config?.approvals?.deny) && config.approvals.deny.length > 0;
+                if (hasAllow || hasDeny)
+                    return discoverPermissionGroups().map(g => g.name);
+            }
+            catch { /* parse fail */ }
+            return [];
+        },
+    };
+}
 const handlers = {
     claude: buildClaudeDetector,
     codex: buildCodexDetector,
@@ -301,6 +364,9 @@ const handlers = {
     droid: buildDroidDetector,
     kiro: buildKiroDetector,
     openclaw: buildOpenClawDetector,
+    copilot: buildCopilotDetector,
+    forge: buildForgeDetector,
+    hermes: buildHermesDetector,
 };
 export const permissionsDetectors = lazyAgentMap(() => {
     const m = {};

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

@@ -73,6 +73,26 @@ function buildWorkflowsDetector(agent) {
                     .filter(d => d.isFile() && d.name.endsWith('.yaml') && !d.name.startsWith('.'))
                     .map(d => d.name.slice(0, -'.yaml'.length));
             }
+            if (agent === 'openclaw') {
+                const dir = path.join(versionHome, '.openclaw', 'workflows');
+                if (!fs.existsSync(dir))
+                    return [];
+                return fs.readdirSync(dir, { withFileTypes: true })
+                    .filter(d => d.isFile() && d.name.endsWith('.lobster') && !d.name.startsWith('.'))
+                    .filter(d => {
+                    try {
+                        const parsed = yaml.parse(fs.readFileSync(path.join(dir, d.name), 'utf-8'));
+                        const env = parsed && typeof parsed === 'object' && parsed.env && typeof parsed.env === 'object' && !Array.isArray(parsed.env)
+                            ? parsed.env
+                            : {};
+                        return env.AGENTS_CLI_WORKFLOW === d.name.slice(0, -'.lobster'.length);
+                    }
+                    catch {
+                        return false;
+                    }
+                })
+                    .map(d => d.name.slice(0, -'.lobster'.length));
+            }
             const workflowsDir = path.join(versionHome, 'workflows');
             if (!fs.existsSync(workflowsDir))
                 return [];

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

@@ -1,5 +1,5 @@
 /**
- * Hooks writer — copies trusted hook script files into `{agentDir}/hooks/`.
+ * Hooks writer — copies trusted hook sources into `{agentDir}/hooks/`.
  * Caller filters by `supports(agent, 'hooks', version)` before invoking.
  * Orphan sweep (delete hooks in version-home that aren't in `availableNames`)
  * stays in the orchestrator since it depends on the broader available set.
@@ -12,6 +12,60 @@ import { safeJoin } from '../../paths.js';
 import { registerHooksToSettings } from '../../hooks.js';
 import { resolveHookSource } from './sources.js';
 import { lazyAgentMap } from './lazy-map.js';
+function removePath(target) {
+    try {
+        const stat = fs.lstatSync(target);
+        if (stat.isSymbolicLink() || stat.isFile()) {
+            fs.unlinkSync(target);
+        }
+        else if (stat.isDirectory()) {
+            fs.rmSync(target, { recursive: true, force: true });
+        }
+    }
+    catch {
+        /* already gone */
+    }
+}
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isSymbolicLink())
+            continue;
+        const srcPath = safeJoin(src, entry.name);
+        const destPath = safeJoin(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        }
+        else if (entry.isFile()) {
+            fs.copyFileSync(srcPath, destPath);
+            fs.chmodSync(destPath, fs.statSync(srcPath).mode);
+        }
+    }
+}
+function copyHookSource(src, dest) {
+    let stat;
+    try {
+        stat = fs.lstatSync(src);
+    }
+    catch {
+        return false;
+    }
+    if (stat.isSymbolicLink())
+        return false;
+    removePath(dest);
+    if (stat.isDirectory()) {
+        copyDir(src, dest);
+        return true;
+    }
+    if (stat.isFile()) {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+        fs.chmodSync(dest, 0o755);
+        return true;
+    }
+    return false;
+}
 function buildHooksWriter(agent) {
     return {
         kind: 'hooks',
@@ -26,9 +80,9 @@ function buildHooksWriter(agent) {
                 if (!srcFile)
                     continue;
                 const destFile = safeJoin(hooksTarget, hook);
-                fs.copyFileSync(srcFile, destFile);
-                fs.chmodSync(destFile, 0o755);
-                synced.push(hook);
+                if (copyHookSource(srcFile, destFile)) {
+                    synced.push(hook);
+                }
             }
             // Native hook registration in settings.json/hooks.json. Grok is included
             // so subrule-bundled guards (absolute paths outside the central hooks/

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

@@ -5,7 +5,7 @@ function buildPermissionsWriter(agent) {
     return {
         kind: 'permissions',
         agent,
-        write({ versionHome, selection }) {
+        write({ versionHome, selection, cwd }) {
             if (selection.length === 0)
                 return { synced: [] };
             const built = buildPermissionsFromGroups(selection);
@@ -13,7 +13,7 @@ function buildPermissionsWriter(agent) {
             const hasDeny = (built.deny?.length ?? 0) > 0;
             if (!hasAllow && !hasDeny)
                 return { synced: [] };
-            const r = applyPermsToVersion(agent, built, versionHome, true);
+            const r = applyPermsToVersion(agent, built, versionHome, true, cwd);
             return { synced: r.success ? selection : [] };
         },
     };

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

@@ -56,7 +56,7 @@ function buildSkillsWriter(agent) {
             fs.mkdirSync(skillsTarget, { recursive: true });
             const synced = [];
             for (const skill of selection) {
-                const srcDir = resolveSkillSource(skill);
+                const srcDir = resolveSkillSource(skill, { agent });
                 if (!srcDir)
                     continue;
                 const destDir = safeJoin(skillsTarget, skill);

package/dist/lib/staleness/writers/sources.d.ts

@@ -1,3 +1,4 @@
+import type { AgentId } from '../../types.js';
 export type EnabledExtra = {
     alias: string;
     dir: string;
@@ -9,7 +10,15 @@ export declare function trustedSourceBases(): {
 /** Find the trusted source for a command markdown by name. */
 export declare function resolveCommandSource(name: string): string | null;
 /** Find the trusted source directory for a skill by name. */
-export declare function resolveSkillSource(name: string): string | null;
+export declare function resolveSkillSource(name: string, options?: {
+    agent?: AgentId;
+    plugins?: Set<string>;
+}): string | null;
+/** List trusted plugin-bundled skill names, filtered to an optional plugin/agent scope. */
+export declare function listPluginSkillNames(options?: {
+    agent?: AgentId;
+    plugins?: Set<string>;
+}): string[];
 /** Find the trusted source file for a hook by name. */
 export declare function resolveHookSource(name: string): string | null;
 /** All trusted command-skill source roots, used to dedup name collisions for commands-as-skills writes. */

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

@@ -35,6 +35,50 @@ function isLiveDir(p) {
         return false;
     }
 }
+function readPluginManifest(pluginRoot) {
+    const manifestPath = path.join(pluginRoot, '.claude-plugin', 'plugin.json');
+    if (!isLiveFile(manifestPath))
+        return null;
+    try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        if (!manifest.name || !manifest.version)
+            return null;
+        return manifest;
+    }
+    catch {
+        return null;
+    }
+}
+function pluginSupportsAgent(manifest, agent) {
+    if (!agent)
+        return true;
+    return !manifest.agents || manifest.agents.length === 0 || manifest.agents.includes(agent);
+}
+function pluginSkillDirs(options = {}) {
+    const dirs = [];
+    for (const base of trustedSourceBases()) {
+        const pluginsDir = path.join(base.dir, 'plugins');
+        let entries;
+        try {
+            entries = fs.readdirSync(pluginsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            if (options.plugins && !options.plugins.has(entry.name))
+                continue;
+            const pluginRoot = path.join(pluginsDir, entry.name);
+            const manifest = readPluginManifest(pluginRoot);
+            if (!manifest || !pluginSupportsAgent(manifest, options.agent))
+                continue;
+            dirs.push(path.join(pluginRoot, 'skills'));
+        }
+    }
+    return dirs;
+}
 /** Find the trusted source for a command markdown by name. */
 export function resolveCommandSource(name) {
     const candidates = [
@@ -45,14 +89,36 @@ export function resolveCommandSource(name) {
     return candidates.find(isLiveFile) ?? null;
 }
 /** Find the trusted source directory for a skill by name. */
-export function resolveSkillSource(name) {
+export function resolveSkillSource(name, options = {}) {
     const candidates = [
         safeJoin(path.join(getUserAgentsDir(), 'skills'), name),
         safeJoin(getSkillsDir(), name),
         ...getEnabledExtraRepos().map((e) => safeJoin(path.join(e.dir, 'skills'), name)),
+        ...pluginSkillDirs(options).map((skillsDir) => safeJoin(skillsDir, name)),
     ];
     return candidates.find(isLiveDir) ?? null;
 }
+/** List trusted plugin-bundled skill names, filtered to an optional plugin/agent scope. */
+export function listPluginSkillNames(options = {}) {
+    const names = new Set();
+    for (const skillsDir of pluginSkillDirs(options)) {
+        let entries;
+        try {
+            entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            if (isLiveFile(path.join(skillsDir, entry.name, 'SKILL.md'))) {
+                names.add(entry.name);
+            }
+        }
+    }
+    return Array.from(names);
+}
 /** Find the trusted source file for a hook by name. */
 export function resolveHookSource(name) {
     const candidates = [
@@ -68,5 +134,6 @@ export function trustedSkillRoots() {
         path.join(getUserAgentsDir(), 'skills'),
         getSkillsDir(),
         ...getEnabledExtraRepos().map((e) => path.join(e.dir, 'skills')),
+        ...pluginSkillDirs(),
     ];
 }