@phnx-labs/agents-cli 1.20.3 → 1.20.5

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

@@ -0,0 +1,111 @@
+/**
+ * Commands writer.
+ *
+ * Two physical formats, picked per-(agent, version) at write time:
+ *
+ *  - command-as-skill — fires when `shouldInstallCommandAsSkill(agent, version)`
+ *    is true. Used for grok (no native commands, but skills/) and Codex
+ *    >= 0.117.0 (commands capability ends, skills capability remains).
+ *    Writes `{agentDir}/skills/<name>/SKILL.md` with the `agents_command`
+ *    marker; the agent picks it up as a slash-command equivalent.
+ *
+ *  - native command file — `{agentDir}/<commandsSubdir>/<name>.md` (or .toml
+ *    when the agent's format is toml). Standard path for Claude, Codex
+ *    < 0.117.0, Gemini, Cursor, OpenCode, Copilot, Amp, Kiro, Roo,
+ *    Antigravity.
+ *
+ * Source resolution is `resolveCommandSource` (user → system → extras —
+ * project layer intentionally excluded).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, agentConfigDirName } from '../../agents.js';
+import { supports } from '../../capabilities.js';
+import { safeJoin } from '../../paths.js';
+import { markdownToToml } from '../../convert.js';
+import { commandAppliesTo, parseCommandMetadata } from '../../commands.js';
+import { installCommandSkillToVersion, shouldInstallCommandAsSkill } from '../../command-skills.js';
+import { resolveCommandSource, trustedSkillRoots } from './sources.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildCommandsWriter(agent) {
+    return {
+        kind: 'commands',
+        agent,
+        write({ version, versionHome, selection }) {
+            const agentConfig = AGENTS[agent];
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
+            const supportsCommands = supports(agent, 'commands', version).ok;
+            // Writers fire only after supports() OR commands-as-skills says yes —
+            // both paths produce a usable result here.
+            if (!commandsAsSkills && !supportsCommands) {
+                throw new Error(`commands writer reached for ${agent}@${version} with no path (cmd=false, asSkill=false)`);
+            }
+            const skillRoots = trustedSkillRoots();
+            const commandsTarget = path.join(agentDir, agentConfig.commandsSubdir);
+            if (!commandsAsSkills) {
+                fs.mkdirSync(commandsTarget, { recursive: true });
+            }
+            const synced = [];
+            for (const cmd of selection) {
+                const srcFile = resolveCommandSource(cmd);
+                if (!srcFile)
+                    continue;
+                const metadata = parseCommandMetadata(srcFile);
+                if (!commandAppliesTo(agent, version, metadata).ok)
+                    continue;
+                if (commandsAsSkills) {
+                    const installed = installCommandSkillToVersion(agentDir, cmd, srcFile, skillRoots);
+                    if (!installed.success)
+                        continue;
+                }
+                else if (agentConfig.format === 'toml') {
+                    const content = fs.readFileSync(srcFile, 'utf-8');
+                    const tomlContent = markdownToToml(cmd, content);
+                    fs.writeFileSync(safeJoin(commandsTarget, `${cmd}.toml`), tomlContent);
+                }
+                else {
+                    fs.copyFileSync(srcFile, safeJoin(commandsTarget, `${cmd}.md`));
+                }
+                synced.push(cmd);
+            }
+            return { synced };
+        },
+    };
+}
+// Built lazily on first access — see lazy-map.ts for the cycle rationale.
+//
+// Registration covers two cases:
+//   - native commands (claude, codex < 0.117.0, gemini, etc.) — `commands` cap
+//   - commands-as-skills (grok, codex >= 0.117.0)
+//
+// Agents that have skills but use a NATIVE non-file slash-command system
+// (openclaw → Gateway-based commands) are NOT registered. The signal is an
+// empty `commandsSubdir`: there's no directory to write to AND the agent
+// doesn't want commands-as-skills either (it has its own runtime command
+// resolver).
+export const commandsWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const id of Object.keys(AGENTS)) {
+        const cfg = AGENTS[id];
+        if (cfg.capabilities.commands === false && (!cfg.skillsDir || cfg.skillsDir === ''))
+            continue;
+        // Native non-file slash-command runtime — no version-home write.
+        if (cfg.capabilities.commands === false && (!cfg.commandsSubdir || cfg.commandsSubdir === '')) {
+            // Grok has empty commandsSubdir AND wants commands-as-skills.
+            // Distinguish: grok has skillsDir set; openclaw also has skillsDir, so we
+            // can't use that. The cleanest signal is the agent's `cliCommand` set —
+            // openclaw flags `commands: false` AND has its Gateway runtime, while
+            // grok flags `commands: false` because grok's slash commands are skills.
+            // We opt in explicitly: only grok takes commands-as-skills today.
+            if (id !== 'grok')
+                continue;
+        }
+        const hasCommands = cfg.capabilities.commands !== false;
+        const hasSkills = cfg.capabilities.skills !== false;
+        if (hasCommands || hasSkills) {
+            m[id] = buildCommandsWriter(id);
+        }
+    }
+    return m;
+});

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

@@ -0,0 +1,3 @@
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const hooksWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

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

@@ -0,0 +1,47 @@
+/**
+ * Hooks writer — copies trusted hook script files 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.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { agentConfigDirName } from '../../agents.js';
+import { capableAgents } from '../../capabilities.js';
+import { safeJoin } from '../../paths.js';
+import { registerHooksToSettings } from '../../hooks.js';
+import { resolveHookSource } from './sources.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildHooksWriter(agent) {
+    return {
+        kind: 'hooks',
+        agent,
+        write({ versionHome, selection }) {
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            const hooksTarget = path.join(agentDir, 'hooks');
+            fs.mkdirSync(hooksTarget, { recursive: true });
+            const synced = [];
+            for (const hook of selection) {
+                const srcFile = resolveHookSource(hook);
+                if (!srcFile)
+                    continue;
+                const destFile = safeJoin(hooksTarget, hook);
+                fs.copyFileSync(srcFile, destFile);
+                fs.chmodSync(destFile, 0o755);
+                synced.push(hook);
+            }
+            // Native hook registration in settings.json/hooks.json. Grok auto-
+            // discovers from ~/.grok/hooks/ so the file copy is sufficient.
+            if (agent === 'claude' || agent === 'codex' || agent === 'gemini' || agent === 'antigravity' || agent === 'kimi') {
+                registerHooksToSettings(agent, versionHome);
+            }
+            return { synced };
+        },
+    };
+}
+export const hooksWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('hooks'))
+        m[agent] = buildHooksWriter(agent);
+    return m;
+});

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

@@ -0,0 +1,10 @@
+/**
+ * Canonical list of resource kinds dispatched through the writer/detector
+ * registry. Each name is the capability name on AgentConfig — except
+ * "permissions", which maps to the legacy capability name "allowlist".
+ */
+import type { CapabilityName } from '../../types.js';
+export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'workflows';
+export declare const ALL_RESOURCE_KINDS: readonly ResourceKind[];
+/** Map kind -> capability name on AgentConfig.capabilities. */
+export declare function kindToCapability(kind: ResourceKind): CapabilityName;

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

@@ -0,0 +1,15 @@
+export const ALL_RESOURCE_KINDS = [
+    'commands',
+    'skills',
+    'hooks',
+    'rules',
+    'mcp',
+    'permissions',
+    'subagents',
+    'plugins',
+    'workflows',
+];
+/** Map kind -> capability name on AgentConfig.capabilities. */
+export function kindToCapability(kind) {
+    return kind === 'permissions' ? 'allowlist' : kind;
+}

package/dist/lib/staleness/writers/lazy-map.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lazy-built per-agent map.
+ *
+ * The writer/detector modules form a circular dependency with agents.ts:
+ * agents.ts → versions.ts → staleness/registry.ts → writers/<kind>.ts →
+ * (capableAgents/AGENTS via capabilities or agents directly). If a writer
+ * module iterates AGENTS at module top-level it fires before the AGENTS
+ * const is initialized through the cycle. Wrapping the per-agent map in a
+ * lazily-evaluated Proxy defers every read until call time, by which point
+ * the cycle has resolved.
+ */
+import type { AgentId } from '../../types.js';
+export declare function lazyAgentMap<T>(build: () => Partial<Record<AgentId, T>>): Partial<Record<AgentId, T>>;

package/dist/lib/staleness/writers/lazy-map.js

@@ -0,0 +1,19 @@
+export function lazyAgentMap(build) {
+    let cache = null;
+    const ensure = () => {
+        if (!cache)
+            cache = build();
+        return cache;
+    };
+    return new Proxy({}, {
+        get(_t, prop) { return ensure()[prop]; },
+        has(_t, prop) { return prop in ensure(); },
+        ownKeys() { return Reflect.ownKeys(ensure()); },
+        getOwnPropertyDescriptor(_t, prop) {
+            const m = ensure();
+            if (prop in m)
+                return { configurable: true, enumerable: true, value: m[prop] };
+            return undefined;
+        },
+    });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * MCP writer — thin dispatcher into `installMcpServers` from `lib/mcp.ts`.
+ *
+ * The per-agent format handling (Claude CLI, Codex TOML, Cursor JSON, etc.)
+ * lives in lib/mcp.ts; we keep it there to avoid the import cycle with
+ * `versions.ts`. The writer simply hands the selection to that function.
+ */
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const mcpWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

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

@@ -0,0 +1,19 @@
+import { capableAgents } from '../../capabilities.js';
+import { installMcpServers } from '../../mcp.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildMcpWriter(agent) {
+    return {
+        kind: 'mcp',
+        agent,
+        write({ version, versionHome, selection, cwd }) {
+            const r = installMcpServers(agent, version, versionHome, selection, { cwd });
+            return { synced: r.applied };
+        },
+    };
+}
+export const mcpWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('mcp'))
+        m[agent] = buildMcpWriter(agent);
+    return m;
+});

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

@@ -0,0 +1,13 @@
+/**
+ * Permissions writer — selection is a list of permission GROUP names. We
+ * build the PermissionSet from the discovered groups, then dispatch into the
+ * per-agent format writer in `lib/permissions.ts:applyPermissionsToVersion`.
+ *
+ * The per-agent format work lives in lib/permissions.ts because the format
+ * conversions (Claude settings.json vs Codex TOML+rules vs Gemini tools vs
+ * Antigravity permissions{} vs Grok [permission].rules) are tightly coupled
+ * to the converters defined alongside them.
+ */
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const permissionsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

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

@@ -0,0 +1,26 @@
+import { capableAgents } from '../../capabilities.js';
+import { applyPermissionsToVersion as applyPermsToVersion, buildPermissionsFromGroups, } from '../../permissions.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildPermissionsWriter(agent) {
+    return {
+        kind: 'permissions',
+        agent,
+        write({ versionHome, selection }) {
+            if (selection.length === 0)
+                return { synced: [] };
+            const built = buildPermissionsFromGroups(selection);
+            const hasAllow = built.allow.length > 0;
+            const hasDeny = (built.deny?.length ?? 0) > 0;
+            if (!hasAllow && !hasDeny)
+                return { synced: [] };
+            const r = applyPermsToVersion(agent, built, versionHome, true);
+            return { synced: r.success ? selection : [] };
+        },
+    };
+}
+export const permissionsWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('allowlist'))
+        m[agent] = buildPermissionsWriter(agent);
+    return m;
+});

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

@@ -0,0 +1,7 @@
+/**
+ * Plugins writer — thin wrapper around `syncPluginToVersion`. Discovery and
+ * per-agent format work lives in lib/plugins.ts.
+ */
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const pluginsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

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

@@ -0,0 +1,31 @@
+import { capableAgents } from '../../capabilities.js';
+import { discoverPlugins, syncPluginToVersion, pluginSupportsAgent, cleanOrphanedPluginSkills } from '../../plugins.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildPluginsWriter(agent) {
+    return {
+        kind: 'plugins',
+        agent,
+        write({ version, versionHome, selection }) {
+            const all = discoverPlugins();
+            const map = new Map(all.map(p => [p.name, p]));
+            // Clean orphan plugin-skills from plugins that no longer exist.
+            cleanOrphanedPluginSkills(agent, versionHome, new Set(all.map(p => p.name)));
+            const synced = [];
+            for (const name of selection) {
+                const plugin = map.get(name);
+                if (!plugin || !pluginSupportsAgent(plugin, agent))
+                    continue;
+                const r = syncPluginToVersion(plugin, agent, versionHome, { version });
+                if (r.success)
+                    synced.push(name);
+            }
+            return { synced };
+        },
+    };
+}
+export const pluginsWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('plugins'))
+        m[agent] = buildPluginsWriter(agent);
+    return m;
+});

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

@@ -0,0 +1,7 @@
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export interface RulesSelection {
+    /** Preset name to compose. Empty string falls through to `"default"` in the composer. */
+    preset: string;
+}
+export declare const rulesWriters: Partial<Record<AgentId, ResourceWriter<RulesSelection>>>;

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

@@ -0,0 +1,55 @@
+/**
+ * Rules writer — composes one instruction file per supported agent.
+ *
+ * Single-target per agent (RulesCapability is `{ file: string } | false`).
+ * The composer in `lib/rules/compose.ts` handles all four layers
+ * (project > user > extras > system). We never write the project layer into
+ * the version home — it's resolved at agents-run time into the workspace
+ * AGENTS.md by `compileRulesForProject`.
+ *
+ * Selection shape: `{ preset: string }`. Use `getActiveRulesPreset(agent,
+ * version)` to derive the preset when the caller has no override.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, agentConfigDirName } from '../../agents.js';
+import { capableAgents } from '../../capabilities.js';
+import { composeRulesFromState } from '../../rules/compose.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildRulesWriter(agent) {
+    return {
+        kind: 'rules',
+        agent,
+        write({ versionHome, selection }) {
+            const cap = AGENTS[agent].capabilities.rules;
+            if (cap === false) {
+                throw new Error(`rules writer reached for ${agent} (rules: false)`);
+            }
+            const targetName = cap.file;
+            const composed = composeRulesFromState({ preset: selection.preset || undefined });
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            // `cap.file` is a trusted constant from AGENTS table; openclaw ships a
+            // nested path (`workspace/AGENTS.md`) so we use path.join rather than
+            // safeJoin (which rejects path separators in `name`).
+            const destFile = path.join(agentDir, targetName);
+            fs.mkdirSync(path.dirname(destFile), { recursive: true });
+            // Remove any pre-existing symlink before writing — a stale symlink
+            // could point at a deleted source and writeFileSync would chase it
+            // to nothing.
+            try {
+                const st = fs.lstatSync(destFile);
+                if (st.isSymbolicLink() || st.isFile())
+                    fs.unlinkSync(destFile);
+            }
+            catch { /* destination did not exist */ }
+            fs.writeFileSync(destFile, composed.content);
+            return { synced: [targetName] };
+        },
+    };
+}
+export const rulesWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('rules'))
+        m[agent] = buildRulesWriter(agent);
+    return m;
+});

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

@@ -0,0 +1,3 @@
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const skillsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

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

@@ -0,0 +1,81 @@
+/**
+ * Skills writer — copies each selected skill directory into
+ * `{agentDir}/skills/<name>/`. Agents flagged `nativeAgentsSkillsDir` (Gemini)
+ * read directly from `~/.agents/skills/` and have no writer registered; the
+ * sync orchestrator clears their version-home skills dir.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, agentConfigDirName } from '../../agents.js';
+import { capableAgents } from '../../capabilities.js';
+import { safeJoin } from '../../paths.js';
+import { resolveSkillSource } from './sources.js';
+import { lazyAgentMap } from './lazy-map.js';
+const SKILL_COPY_IGNORE = new Set(['.DS_Store', '.git', '.gitignore', '.venv', '__pycache__', 'node_modules']);
+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;
+        if (SKILL_COPY_IGNORE.has(entry.name))
+            continue;
+        const s = safeJoin(src, entry.name);
+        const d = safeJoin(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(s, d);
+        }
+        else if (entry.isFile()) {
+            fs.copyFileSync(s, d);
+        }
+    }
+}
+function removePath(p) {
+    try {
+        const st = fs.lstatSync(p);
+        if (st.isSymbolicLink() || st.isFile())
+            fs.unlinkSync(p);
+        else if (st.isDirectory())
+            fs.rmSync(p, { recursive: true, force: true });
+    }
+    catch { /* already gone */ }
+}
+function buildSkillsWriter(agent) {
+    return {
+        kind: 'skills',
+        agent,
+        write({ versionHome, selection }) {
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            const skillsTarget = path.join(agentDir, 'skills');
+            try {
+                if (fs.lstatSync(skillsTarget).isSymbolicLink()) {
+                    removePath(skillsTarget);
+                }
+            }
+            catch { /* does not exist yet */ }
+            fs.mkdirSync(skillsTarget, { recursive: true });
+            const synced = [];
+            for (const skill of selection) {
+                const srcDir = resolveSkillSource(skill);
+                if (!srcDir)
+                    continue;
+                const destDir = safeJoin(skillsTarget, skill);
+                removePath(destDir);
+                copyDir(srcDir, destDir);
+                synced.push(skill);
+            }
+            return { synced };
+        },
+    };
+}
+export const skillsWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('skills')) {
+        // Agents that natively read ~/.agents/skills/ don't get a version-home
+        // write — the orchestrator clears the dir for them.
+        if (AGENTS[agent].nativeAgentsSkillsDir)
+            continue;
+        m[agent] = buildSkillsWriter(agent);
+    }
+    return m;
+});

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

@@ -0,0 +1,16 @@
+export type EnabledExtra = {
+    alias: string;
+    dir: string;
+};
+/** Trusted source bases for content-like kinds. Project layer excluded. */
+export declare function trustedSourceBases(): {
+    dir: string;
+}[];
+/** 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;
+/** 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. */
+export declare function trustedSkillRoots(): string[];

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

@@ -0,0 +1,72 @@
+/**
+ * Shared layer-source resolution for writers.
+ *
+ * Layer precedence matches getResourceBases() in versions.ts. Project layer
+ * is intentionally EXCLUDED for commands/skills/hooks/subagents/permissions
+ * — those bodies become agent context, and a cloned public repo could ship
+ * one that coerces the agent on the next launch. Trusted layers only:
+ * user → system → extras.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getUserAgentsDir, getAgentsDir, getEnabledExtraRepos, getCommandsDir, getSkillsDir, getHooksDir } from '../../state.js';
+import { safeJoin } from '../../paths.js';
+/** Trusted source bases for content-like kinds. Project layer excluded. */
+export function trustedSourceBases() {
+    return [
+        { dir: getUserAgentsDir() },
+        { dir: getAgentsDir() },
+        ...getEnabledExtraRepos().map((e) => ({ dir: e.dir })),
+    ];
+}
+function isLiveFile(p) {
+    try {
+        return fs.existsSync(p) && !fs.lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function isLiveDir(p) {
+    try {
+        return fs.existsSync(p) && !fs.lstatSync(p).isSymbolicLink() && fs.lstatSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Find the trusted source for a command markdown by name. */
+export function resolveCommandSource(name) {
+    const candidates = [
+        safeJoin(path.join(getUserAgentsDir(), 'commands'), `${name}.md`),
+        safeJoin(getCommandsDir(), `${name}.md`),
+        ...getEnabledExtraRepos().map((e) => safeJoin(path.join(e.dir, 'commands'), `${name}.md`)),
+    ];
+    return candidates.find(isLiveFile) ?? null;
+}
+/** Find the trusted source directory for a skill by name. */
+export function resolveSkillSource(name) {
+    const candidates = [
+        safeJoin(path.join(getUserAgentsDir(), 'skills'), name),
+        safeJoin(getSkillsDir(), name),
+        ...getEnabledExtraRepos().map((e) => safeJoin(path.join(e.dir, 'skills'), name)),
+    ];
+    return candidates.find(isLiveDir) ?? null;
+}
+/** Find the trusted source file for a hook by name. */
+export function resolveHookSource(name) {
+    const candidates = [
+        safeJoin(path.join(getUserAgentsDir(), 'hooks'), name),
+        safeJoin(getHooksDir(), name),
+        ...getEnabledExtraRepos().map((e) => safeJoin(path.join(e.dir, 'hooks'), name)),
+    ];
+    return candidates.find(isLiveFile) ?? null;
+}
+/** All trusted command-skill source roots, used to dedup name collisions for commands-as-skills writes. */
+export function trustedSkillRoots() {
+    return [
+        path.join(getUserAgentsDir(), 'skills'),
+        getSkillsDir(),
+        ...getEnabledExtraRepos().map((e) => path.join(e.dir, 'skills')),
+    ];
+}

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

@@ -0,0 +1,3 @@
+import type { AgentId } from '../../types.js';
+import type { ResourceWriter } from './types.js';
+export declare const subagentsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;

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

@@ -0,0 +1,53 @@
+/**
+ * Subagents writer. Claude flattens each subagent into a single .md file
+ * under `<agentDir>/agents/`. OpenClaw copies the full subagent directory
+ * (with AGENT.md renamed to AGENTS.md) into `<versionHome>/.openclaw/<name>/`.
+ *
+ * Source-side discovery is `listInstalledSubagents` from lib/subagents.ts —
+ * it reads user + system layers only (project layer excluded for the same
+ * defense as commands/skills/hooks).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { capableAgents } from '../../capabilities.js';
+import { listInstalledSubagents, transformSubagentForClaude, syncSubagentToOpenclaw } from '../../subagents.js';
+import { safeJoin } from '../../paths.js';
+import { lazyAgentMap } from './lazy-map.js';
+function buildSubagentsWriter(agent) {
+    return {
+        kind: 'subagents',
+        agent,
+        write({ versionHome, selection }) {
+            const all = listInstalledSubagents();
+            const map = new Map(all.map(s => [s.name, s]));
+            const synced = [];
+            for (const name of selection) {
+                const sub = map.get(name);
+                if (!sub)
+                    continue;
+                try {
+                    if (agent === 'claude') {
+                        const agentsDir = path.join(versionHome, '.claude', 'agents');
+                        fs.mkdirSync(agentsDir, { recursive: true });
+                        fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.md`), transformSubagentForClaude(sub.path));
+                        synced.push(sub.name);
+                    }
+                    else if (agent === 'openclaw') {
+                        const target = safeJoin(path.join(versionHome, '.openclaw'), sub.name);
+                        const r = syncSubagentToOpenclaw(sub.path, target);
+                        if (r.success)
+                            synced.push(sub.name);
+                    }
+                }
+                catch { /* per-item sync failure: skip */ }
+            }
+            return { synced };
+        },
+    };
+}
+export const subagentsWriters = lazyAgentMap(() => {
+    const m = {};
+    for (const agent of capableAgents('subagents'))
+        m[agent] = buildSubagentsWriter(agent);
+    return m;
+});