@phnx-labs/agents-cli 1.20.72 → 1.20.74

package/dist/lib/permissions.js

@@ -433,14 +433,27 @@ export function removePermissionSet(name) {
 // ============================================================================
 // Agent-specific converters
 // ============================================================================
+/**
+ * Map a canonical rule to Claude settings.json syntax.
+ * Claude's file-permission checks only match Edit(path) rules — an Edit rule
+ * covers every file-editing tool (Write, Edit, NotebookEdit) — and Claude
+ * warns at startup about unmatched Write(path) rules. Canonical Write(path)
+ * stays for other agents' converters; for Claude it is emitted as Edit(path).
+ */
+function canonicalToClaudeRule(perm) {
+    if (perm.startsWith('Write(')) {
+        return perm.replace(/^Write/, 'Edit');
+    }
+    return perm;
+}
 /**
  * Convert canonical permission set to Claude format.
  * Claude uses: { permissions: { allow: ["Bash(*)", "Read(**)"], deny: [] } }
  */
 export function convertToClaudeFormat(set) {
     const permissions = {
-        allow: [...set.allow],
-        deny: set.deny ? [...set.deny] : [],
+        allow: [...new Set(set.allow.map(canonicalToClaudeRule))],
+        deny: set.deny ? [...new Set(set.deny.map(canonicalToClaudeRule))] : [],
     };
     if (set.additionalDirectories?.length) {
         permissions.additionalDirectories = [...set.additionalDirectories];
@@ -540,6 +553,89 @@ function normalizeBashPattern(pattern) {
         return pattern.slice(0, -2) + ' *';
     return pattern;
 }
+function canonicalBashToCopilotCommandIdentifier(pattern) {
+    if (pattern === '*' || pattern === '**')
+        return null;
+    if (pattern.endsWith(':*'))
+        return pattern;
+    if (pattern.endsWith(' *'))
+        return `${pattern.slice(0, -2)}:*`;
+    return pattern;
+}
+function canonicalToCopilotMcpApproval(parsed) {
+    const parts = parsed.pattern.split(/[.:/]/).filter(Boolean);
+    if (parts.length === 0)
+        return null;
+    const [serverName, toolName] = parts;
+    return { kind: 'mcp', serverName, toolName: toolName ?? null };
+}
+function canonicalToCopilotApproval(permission) {
+    const parsed = parseCanonicalPattern(permission);
+    if (!parsed)
+        return null;
+    if (parsed.tool === 'bash') {
+        const identifier = canonicalBashToCopilotCommandIdentifier(parsed.pattern);
+        return identifier ? { kind: 'commands', commandIdentifiers: [identifier] } : null;
+    }
+    if ((parsed.tool === 'write' || parsed.tool === 'edit') && (parsed.pattern === '*' || parsed.pattern === '**')) {
+        return { kind: 'write' };
+    }
+    if (parsed.tool === 'read' && (parsed.pattern === '*' || parsed.pattern === '**')) {
+        return { kind: 'read' };
+    }
+    if (parsed.tool === 'mcp') {
+        return canonicalToCopilotMcpApproval(parsed);
+    }
+    return null;
+}
+function mergeCopilotApprovals(existing, incoming) {
+    const byKey = new Map();
+    const add = (approval) => {
+        if (approval.kind === 'commands') {
+            const current = byKey.get('commands');
+            const commandIdentifiers = new Set([...(current?.commandIdentifiers ?? []), ...approval.commandIdentifiers]);
+            byKey.set('commands', { kind: 'commands', commandIdentifiers: Array.from(commandIdentifiers).sort() });
+            return;
+        }
+        byKey.set(JSON.stringify(approval), approval);
+    };
+    for (const approval of existing) {
+        if (!approval || typeof approval !== 'object' || Array.isArray(approval))
+            continue;
+        const record = approval;
+        if (record.kind === 'commands' && Array.isArray(record.commandIdentifiers)) {
+            add({ kind: 'commands', commandIdentifiers: record.commandIdentifiers.filter((v) => typeof v === 'string') });
+        }
+        else if (record.kind === 'read' || record.kind === 'write') {
+            add({ kind: record.kind });
+        }
+        else if (record.kind === 'mcp' && typeof record.serverName === 'string' && (typeof record.toolName === 'string' || record.toolName === null)) {
+            add({ kind: 'mcp', serverName: record.serverName, toolName: record.toolName });
+        }
+    }
+    for (const approval of incoming)
+        add(approval);
+    return Array.from(byKey.values());
+}
+export function convertToCopilotFormat(set, location) {
+    const approvals = [];
+    for (const permission of set.allow) {
+        const approval = canonicalToCopilotApproval(permission);
+        if (approval)
+            approvals.push(approval);
+    }
+    const allowedDirectories = (set.additionalDirectories ?? [])
+        .filter((dir) => dir.trim().length > 0)
+        .map((dir) => path.isAbsolute(dir) ? dir : path.resolve(location, dir));
+    return {
+        locations: {
+            [location]: {
+                ...(approvals.length > 0 ? { tool_approvals: mergeCopilotApprovals([], approvals) } : {}),
+                ...(allowedDirectories.length > 0 ? { allowed_directories: Array.from(new Set(allowedDirectories)).sort() } : {}),
+            },
+        },
+    };
+}
 /** Convert canonical Bash rules into Droid's command arrays. */
 export function convertToDroidFormat(set) {
     const commands = (permissions) => {
@@ -614,6 +710,83 @@ export function convertToOpenClawFormat(set) {
         deny: map(set.deny ?? []),
     };
 }
+const FORGE_OPERATION_BY_CANONICAL = {
+    bash: 'command',
+    read: 'read',
+    grep: 'read',
+    glob: 'read',
+    write: 'write',
+    edit: 'write',
+    notebookedit: 'write',
+    webfetch: 'url',
+    websearch: 'url',
+};
+function canonicalToForgePolicy(perm, permission) {
+    if (BLANKET_BASH_FORMS.has(perm)) {
+        return { permission, rule: { command: '*' } };
+    }
+    const parsed = parseCanonicalPattern(perm);
+    if (!parsed)
+        return null;
+    const operation = FORGE_OPERATION_BY_CANONICAL[parsed.tool];
+    if (!operation)
+        return null;
+    const pattern = parsed.tool === 'bash'
+        ? normalizeBashPattern(parsed.pattern)
+        : (parsed.tool === 'webfetch' || parsed.tool === 'websearch') && parsed.pattern.startsWith('domain:')
+            ? `${parsed.pattern.slice('domain:'.length)}*`
+            : parsed.pattern === '**'
+                ? '**/*'
+                : parsed.pattern;
+    return { permission, rule: { [operation]: pattern } };
+}
+/**
+ * Convert canonical permissions to ForgeCode's permissions.yaml policy list.
+ *
+ * ForgeCode gates built-in tools by operation family (`read`, `write`,
+ * `command`, `url`) plus glob patterns, optionally scoped by `dir`. The policy
+ * file is ignored unless `.forge.toml` has `restricted = true`, and MCP tools
+ * bypass permissions.yaml entirely; agents-cli therefore maps only canonical
+ * built-in allow/deny rules and does not try to express per-named-MCP-tool
+ * grants.
+ */
+export function convertToForgeFormat(set) {
+    const policies = [];
+    const seen = new Set();
+    const add = (policy) => {
+        if (!policy)
+            return;
+        const key = `${policy.permission}|${JSON.stringify(policy.rule)}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        policies.push(policy);
+    };
+    for (const perm of set.allow)
+        add(canonicalToForgePolicy(perm, 'allow'));
+    for (const perm of set.deny ?? [])
+        add(canonicalToForgePolicy(perm, 'deny'));
+    return { policies };
+}
+export function convertToHermesFormat(set) {
+    const commands = (permissions) => {
+        const out = new Set();
+        for (const perm of permissions) {
+            if (BLANKET_BASH_FORMS.has(perm)) {
+                out.add('*');
+                continue;
+            }
+            const parsed = parseCanonicalPattern(perm);
+            if (parsed?.tool === 'bash')
+                out.add(normalizeBashPattern(parsed.pattern));
+        }
+        return Array.from(out).sort();
+    };
+    return {
+        command_allowlist: commands(set.allow),
+        approvals: { deny: commands(set.deny ?? []) },
+    };
+}
 /**
  * Convert canonical permission set to Antigravity format.
  * Antigravity reads ~/.gemini/antigravity-cli/settings.json with
@@ -1144,8 +1317,9 @@ export function applyClaudePermissions(set, scope = 'user', cwd, merge = true) {
         const newPermissions = convertToClaudeFormat(set);
         if (merge && config.permissions) {
             const existing = config.permissions;
-            const mergedAllow = new Set([...(existing.allow || []), ...newPermissions.permissions.allow]);
-            const mergedDeny = new Set([...(existing.deny || []), ...newPermissions.permissions.deny]);
+            // Rewrite stale Write(path) rules already installed in settings.json too.
+            const mergedAllow = new Set([...(existing.allow || []).map(canonicalToClaudeRule), ...newPermissions.permissions.allow]);
+            const mergedDeny = new Set([...(existing.deny || []).map(canonicalToClaudeRule), ...newPermissions.permissions.deny]);
             config.permissions = {
                 allow: [...mergedAllow],
                 deny: [...mergedDeny],
@@ -1292,7 +1466,7 @@ function applyPermissionsToAgent(agentId, set, scope = 'user', cwd, merge = true
  * Apply a permission set to a specific version's home directory.
  * This writes to {versionHome}/.{agent}/settings.json (or equivalent).
  */
-export function applyPermissionsToVersion(agentId, set, versionHome, merge = true) {
+export function applyPermissionsToVersion(agentId, set, versionHome, merge = true, cwd) {
     const configDir = path.join(versionHome, agentConfigDirName(agentId));
     try {
         fs.mkdirSync(configDir, { recursive: true });
@@ -1305,8 +1479,9 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             const newPermissions = convertToClaudeFormat(set);
             if (merge && config.permissions) {
                 const existing = config.permissions;
-                const mergedAllow = new Set([...(existing.allow || []), ...newPermissions.permissions.allow]);
-                const mergedDeny = new Set([...(existing.deny || []), ...newPermissions.permissions.deny]);
+                // Rewrite stale Write(path) rules already installed in settings.json too.
+                const mergedAllow = new Set([...(existing.allow || []).map(canonicalToClaudeRule), ...newPermissions.permissions.allow]);
+                const mergedDeny = new Set([...(existing.deny || []).map(canonicalToClaudeRule), ...newPermissions.permissions.deny]);
                 const mergedDirs = new Set([...(existing.additionalDirectories || []), ...(newPermissions.permissions.additionalDirectories || [])]);
                 const perms = {
                     allow: [...mergedAllow],
@@ -1593,6 +1768,50 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
             return { success: true };
         }
+        if (agentId === 'copilot') {
+            const configPath = path.join(versionHome, '.copilot', 'permissions-config.json');
+            let config = { locations: {} };
+            if (fs.existsSync(configPath)) {
+                config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            }
+            const location = path.resolve(cwd ?? process.cwd());
+            const converted = convertToCopilotFormat(set, location);
+            const incoming = converted.locations[location]?.tool_approvals ?? [];
+            const incomingDirectories = converted.locations[location]?.allowed_directories ?? [];
+            if (merge && incoming.length === 0 && incomingDirectories.length === 0)
+                return { success: true };
+            const locations = (typeof config.locations === 'object' && config.locations !== null && !Array.isArray(config.locations))
+                ? config.locations
+                : {};
+            const existingLocation = (typeof locations[location] === 'object' && locations[location] !== null && !Array.isArray(locations[location]))
+                ? locations[location]
+                : {};
+            const existingApprovals = Array.isArray(existingLocation.tool_approvals) ? existingLocation.tool_approvals : [];
+            const nextApprovals = merge ? mergeCopilotApprovals(existingApprovals, incoming) : incoming;
+            const existingDirectories = Array.isArray(existingLocation.allowed_directories)
+                ? existingLocation.allowed_directories.filter((v) => typeof v === 'string')
+                : [];
+            const nextDirectories = merge
+                ? Array.from(new Set([...existingDirectories, ...incomingDirectories])).sort()
+                : incomingDirectories;
+            const nextLocation = { ...existingLocation };
+            if (nextApprovals.length > 0)
+                nextLocation.tool_approvals = nextApprovals;
+            else
+                delete nextLocation.tool_approvals;
+            if (nextDirectories.length > 0)
+                nextLocation.allowed_directories = nextDirectories;
+            else
+                delete nextLocation.allowed_directories;
+            if (Object.keys(nextLocation).length > 0)
+                locations[location] = nextLocation;
+            else
+                delete locations[location];
+            config.locations = locations;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            return { success: true };
+        }
         if (agentId === 'kiro') {
             const permissionsPath = path.join(versionHome, '.kiro', 'settings', 'permissions.yaml');
             let config = {};
@@ -1669,6 +1888,64 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
             return { success: true };
         }
+        if (agentId === 'forge') {
+            const permissionsPath = path.join(versionHome, '.forge', 'permissions.yaml');
+            let config = {};
+            if (fs.existsSync(permissionsPath)) {
+                const parsed = yaml.parse(fs.readFileSync(permissionsPath, 'utf-8'));
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    config = parsed;
+                }
+            }
+            const newPolicies = convertToForgeFormat(set).policies;
+            if (merge) {
+                const existingPolicies = Array.isArray(config.policies) ? config.policies : [];
+                const seen = new Set();
+                config.policies = [...existingPolicies, ...newPolicies].filter((policy) => {
+                    if (!policy || typeof policy !== 'object' || Array.isArray(policy))
+                        return false;
+                    const key = JSON.stringify(policy);
+                    if (seen.has(key))
+                        return false;
+                    seen.add(key);
+                    return true;
+                });
+            }
+            else {
+                config.policies = newPolicies;
+            }
+            fs.mkdirSync(path.dirname(permissionsPath), { recursive: true });
+            fs.writeFileSync(permissionsPath, yaml.stringify(config), 'utf-8');
+            return { success: true };
+        }
+        if (agentId === 'hermes') {
+            const configPath = path.join(versionHome, '.hermes', 'config.yaml');
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                const parsed = yaml.parse(fs.readFileSync(configPath, 'utf-8'));
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    config = parsed;
+                }
+            }
+            const converted = convertToHermesFormat(set);
+            const approvals = (typeof config.approvals === 'object' && config.approvals !== null && !Array.isArray(config.approvals))
+                ? config.approvals
+                : {};
+            if (merge) {
+                const existingAllow = Array.isArray(config.command_allowlist) ? config.command_allowlist : [];
+                const existingDeny = Array.isArray(approvals.deny) ? approvals.deny : [];
+                config.command_allowlist = Array.from(new Set([...existingAllow, ...converted.command_allowlist])).sort();
+                approvals.deny = Array.from(new Set([...existingDeny, ...converted.approvals.deny])).sort();
+            }
+            else {
+                config.command_allowlist = converted.command_allowlist;
+                approvals.deny = converted.approvals.deny;
+            }
+            config.approvals = approvals;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, yaml.stringify(config), 'utf-8');
+            return { success: true };
+        }
         return { success: false, error: `Agent '${agentId}' does not support permissions` };
     }
     catch (err) {

package/dist/lib/project-launch.d.ts

@@ -8,18 +8,12 @@
  *    (+ per-agent symlinks). Delegates to compileRulesForProject, which is
  *    the same helper management-side `agents sync` uses.
  *
- * 2. Mirror project resources from `<cwd>/.agents/{subagents,commands,skills}`
- *    into the agent's workspace-local discovery dirs (`<cwd>/.claude/agents/`,
- *    `<cwd>/.claude/commands/`, `<cwd>/.claude/skills/`). File-level symlinks
- *    so edits in the source dir are live without re-sync. Skips any dest
- *    entry that already exists and isn't one of our symlinks (don't-clobber).
- *    v1: claude-only. Other agents have varying workspace conventions (amp
- *    uses `~/.config/amp`, antigravity uses `~/.gemini/antigravity-cli`,
- *    codex/gemini/cursor lack subagent support entirely) — they're follow-up
- *    material. NOTE: `.mcp.json` is intentionally NOT auto-symlinked from
- *    the launch path — that's a supply-chain surface (cloning a hostile
- *    repo would auto-register an attacker MCP server). Belongs to full
- *    `agents sync` with explicit opt-in, not the hot path.
+ * 2. Copy project resources from `<cwd>/.agents/{commands,skills,subagents,workflows}`
+ *    into the agent's workspace-local discovery dir (`<cwd>/.claude/`,
+ *    `<cwd>/.codex/`, etc.) with an ownership manifest at
+ *    `<cwd>/.{agent}/.agents-managed.json`. The manifest is the only clobber
+ *    authority: paths it lists are removed and refreshed, pre-existing paths it
+ *    does not list are skipped as user-owned.
  *
  * 3. Synthesize four scope-grouped plugin marketplaces under the version's
  *    `<versionHome>/.{agent}/plugins/marketplaces/` (for plugin-capable agents):

package/dist/lib/project-launch.js

@@ -8,18 +8,12 @@
  *    (+ per-agent symlinks). Delegates to compileRulesForProject, which is
  *    the same helper management-side `agents sync` uses.
  *
- * 2. Mirror project resources from `<cwd>/.agents/{subagents,commands,skills}`
- *    into the agent's workspace-local discovery dirs (`<cwd>/.claude/agents/`,
- *    `<cwd>/.claude/commands/`, `<cwd>/.claude/skills/`). File-level symlinks
- *    so edits in the source dir are live without re-sync. Skips any dest
- *    entry that already exists and isn't one of our symlinks (don't-clobber).
- *    v1: claude-only. Other agents have varying workspace conventions (amp
- *    uses `~/.config/amp`, antigravity uses `~/.gemini/antigravity-cli`,
- *    codex/gemini/cursor lack subagent support entirely) — they're follow-up
- *    material. NOTE: `.mcp.json` is intentionally NOT auto-symlinked from
- *    the launch path — that's a supply-chain surface (cloning a hostile
- *    repo would auto-register an attacker MCP server). Belongs to full
- *    `agents sync` with explicit opt-in, not the hot path.
+ * 2. Copy project resources from `<cwd>/.agents/{commands,skills,subagents,workflows}`
+ *    into the agent's workspace-local discovery dir (`<cwd>/.claude/`,
+ *    `<cwd>/.codex/`, etc.) with an ownership manifest at
+ *    `<cwd>/.{agent}/.agents-managed.json`. The manifest is the only clobber
+ *    authority: paths it lists are removed and refreshed, pre-existing paths it
+ *    does not list are skipped as user-owned.
  *
  * 3. Synthesize four scope-grouped plugin marketplaces under the version's
  *    `<versionHome>/.{agent}/plugins/marketplaces/` (for plugin-capable agents):
@@ -48,8 +42,8 @@ import { supports } from './capabilities.js';
 import { getEnabledExtraRepos, getExtraPluginsDir, getPluginsDir, getProjectAgentsDir, getProjectPluginsDir, getSystemPluginsDir, } from './state.js';
 import { getVersionHomePath } from './versions.js';
 import { toPortableKey } from './platform/index.js';
-import { transformSubagentForClaude } from './subagents.js';
 import { compileRulesForProject } from './rules/compile.js';
+import { syncProjectResourcesToAgent } from './project-resources.js';
 import { discoverPluginsInDir, hasPluginExecSurfaces, inspectPluginCapabilities } from './plugins.js';
 import { MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, addPluginToSettings, copyPluginToMarketplace, marketplaceNameFor, marketplaceRoot, pluginInstallDir, registerMarketplace, removePluginFromSettings, syncMarketplaceManifest, } from './plugin-marketplace.js';
 /**
@@ -77,9 +71,12 @@ export function runLaunchSync(opts) {
         // Don't fail launch on a malformed project rules.yaml.
     }
     // Step 2: workspace resource mirror
-    const mirror = mirrorWorkspaceResources(opts.cwd, opts.agent);
-    result.workspaceLinks = mirror.links;
-    result.workspaceSkipped = mirror.skipped;
+    const projectAgentsDir = getProjectAgentsDir(opts.cwd);
+    if (projectAgentsDir) {
+        const projectResources = syncProjectResourcesToAgent(opts.agent, opts.version, projectAgentsDir);
+        result.workspaceLinks = projectResources.synced.length;
+        result.workspaceSkipped = projectResources.skipped;
+    }
     // Step 3: scoped plugin marketplaces
     result.marketplaces = synthesizeScopedMarketplaces(opts.agent, opts.version, opts.cwd);
     // Touch the shim's skip-fast sentinel. Best-effort — if this fails the
@@ -117,218 +114,6 @@ function touchLaunchSentinel(agent, version, cwd) {
         // best-effort
     }
 }
-const CLAUDE_MIRROR_PLANS = [
-    { srcSubdir: 'subagents', destSubdir: 'agents', mode: 'subagent-write' },
-    { srcSubdir: 'commands', destSubdir: 'commands', mode: 'file-symlink' },
-    { srcSubdir: 'skills', destSubdir: 'skills', mode: 'dir-symlink' },
-];
-/**
- * Marker prepended-as-trailing-comment to every subagent file WE generate.
- * It's an HTML comment — invisible to the markdown the agent reads — placed on
- * the last line so it never disturbs the leading `---` frontmatter block.
- *
- * Ownership rule (the one don't-clobber decision for written, non-symlink
- * files): we only overwrite a `.claude/agents/<name>.md` whose content carries
- * this marker. A user-authored file (no marker) or a symlink at the dest is
- * left untouched. A marker beats an mtime/sidecar sentinel because it travels
- * with the file across copies and git, and needs no out-of-band state.
- */
-const GENERATED_SUBAGENT_MARKER = '<!-- agents-cli:generated-subagent';
-function mirrorWorkspaceResources(cwd, agent) {
-    // v1: claude-only. Other agents have workspace conventions we haven't
-    // mapped (amp: ~/.config/amp; antigravity: ~/.gemini/antigravity-cli;
-    // codex/gemini/cursor: no subagent support per capabilities). Adding them
-    // requires per-agent workspaceDirName + capability gates — follow-up.
-    if (agent !== 'claude')
-        return { links: 0, skipped: [] };
-    const projectAgentsDir = getProjectAgentsDir(cwd);
-    if (!projectAgentsDir)
-        return { links: 0, skipped: [] };
-    const agentWorkspaceDir = path.join(cwd, '.claude');
-    const projectAgentsResolved = (() => {
-        try {
-            return fs.realpathSync(projectAgentsDir);
-        }
-        catch {
-            return path.resolve(projectAgentsDir);
-        }
-    })();
-    let links = 0;
-    const skipped = [];
-    // Mirror subagents / commands / skills. mcp.json is intentionally excluded
-    // — see header doc, it's a supply-chain surface.
-    for (const plan of CLAUDE_MIRROR_PLANS) {
-        const srcDir = path.join(projectAgentsDir, plan.srcSubdir);
-        if (!fs.existsSync(srcDir))
-            continue;
-        const destDir = path.join(agentWorkspaceDir, plan.destSubdir);
-        fs.mkdirSync(destDir, { recursive: true });
-        // Subagents flatten N source files into one written .md — not a symlink.
-        if (plan.mode === 'subagent-write') {
-            const r = writeProjectSubagents(srcDir, destDir, cwd);
-            links += r.links;
-            skipped.push(...r.skipped);
-            continue;
-        }
-        const entries = fs.readdirSync(srcDir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (entry.name.startsWith('.'))
-                continue;
-            if (plan.mode === 'dir-symlink' && !entry.isDirectory())
-                continue;
-            if (plan.mode === 'file-symlink' && !entry.isFile() && !entry.isSymbolicLink())
-                continue;
-            const srcPath = path.join(srcDir, entry.name);
-            const destPath = path.join(destDir, entry.name);
-            if (replaceWithSymlinkIfOwned(srcPath, destPath, projectAgentsResolved)) {
-                links += 1;
-            }
-            else {
-                skipped.push(path.relative(cwd, destPath));
-            }
-        }
-    }
-    return { links, skipped };
-}
-/**
- * Mirror project subagents into `<cwd>/.claude/agents/`. The canonical source
- * shape is a DIRECTORY containing AGENT.md (e.g. `.agents/subagents/probe/AGENT.md`)
- * — confirmed by the detector (versions.ts) and lister (subagents.ts). Each
- * such directory is flattened via transformSubagentForClaude (the exact writer
- * the version-home sync uses) into a single `<name>.md`, then written under an
- * ownership marker so a re-launch refreshes our file but never clobbers a
- * user-authored one.
- *
- * Returns the same {links, skipped} shape the symlink path reports, so the
- * caller's accounting is uniform across resource kinds.
- */
-function writeProjectSubagents(srcDir, destDir, cwd) {
-    let links = 0;
-    const skipped = [];
-    for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-        if (entry.name.startsWith('.'))
-            continue;
-        if (!entry.isDirectory())
-            continue;
-        const subagentDir = path.join(srcDir, entry.name);
-        if (!fs.existsSync(path.join(subagentDir, 'AGENT.md')))
-            continue;
-        const destPath = path.join(destDir, `${entry.name}.md`);
-        if (writeSubagentIfOwned(subagentDir, destPath)) {
-            links += 1;
-        }
-        else {
-            skipped.push(path.relative(cwd, destPath));
-        }
-    }
-    return { links, skipped };
-}
-/**
- * Write a flattened subagent file at `destPath`, refusing to clobber user state.
- *
- *   - dest missing            → write fresh.
- *   - dest is our generation  → overwrite (refresh; carries GENERATED_SUBAGENT_MARKER).
- *   - dest is a symlink / any
- *     non-regular file         → SKIP (user state we don't own).
- *   - dest is a regular file
- *     without our marker        → SKIP (hand-authored .claude/agents/<name>.md).
- *
- * Returns true when our file is present (written now or already current),
- * false when we left a user-owned dest alone.
- */
-function writeSubagentIfOwned(subagentDir, destPath) {
-    let existing = null;
-    let destLstat = null;
-    try {
-        destLstat = fs.lstatSync(destPath);
-    }
-    catch { /* missing — write fresh */ }
-    if (destLstat) {
-        if (!destLstat.isFile())
-            return false; // symlink/dir/etc. — user state
-        try {
-            existing = fs.readFileSync(destPath, 'utf-8');
-        }
-        catch {
-            return false;
-        }
-        if (!existing.includes(GENERATED_SUBAGENT_MARKER))
-            return false; // hand-authored
-    }
-    let body;
-    try {
-        body = transformSubagentForClaude(subagentDir);
-    }
-    catch {
-        return false; // malformed AGENT.md — don't write a broken file
-    }
-    const content = `${body}\n\n${GENERATED_SUBAGENT_MARKER} — edit .agents/subagents/${path.basename(subagentDir)}/ instead -->\n`;
-    // Skip-fast: identical content already on disk → no write (keeps mtime stable).
-    if (existing === content)
-        return true;
-    try {
-        fs.mkdirSync(path.dirname(destPath), { recursive: true });
-        fs.writeFileSync(destPath, content);
-    }
-    catch {
-        return false;
-    }
-    return true;
-}
-/**
- * Create or refresh a symlink at `destPath` pointing at `srcPath`. Returns
- * true if we wrote (or already had) the link, false if we skipped because
- * the destination is user-owned (regular file, directory, or symlink pointing
- * outside the project's `.agents/` tree, or a dangling symlink — treated as
- * user state we don't yet understand).
- *
- * Skip-fast: if the destination is already a symlink resolving to the
- * project-agents tree AND its target matches srcPath, no write happens.
- */
-function replaceWithSymlinkIfOwned(srcPath, destPath, projectAgentsResolved) {
-    let destLstat = null;
-    try {
-        destLstat = fs.lstatSync(destPath);
-    }
-    catch { /* missing — write fresh */ }
-    if (destLstat) {
-        if (!destLstat.isSymbolicLink()) {
-            return false;
-        }
-        let destTargetReal = null;
-        try {
-            destTargetReal = fs.realpathSync(destPath);
-        }
-        catch { /* dangling */ }
-        // Dangling symlink → user-owned in-progress state; do not clobber.
-        if (destTargetReal === null) {
-            return false;
-        }
-        if (destTargetReal !== projectAgentsResolved && !destTargetReal.startsWith(projectAgentsResolved + path.sep)) {
-            return false;
-        }
-        let srcReal = null;
-        try {
-            srcReal = fs.realpathSync(srcPath);
-        }
-        catch { /* src vanished mid-launch */ }
-        if (srcReal !== null && destTargetReal === srcReal) {
-            return true; // already correct
-        }
-        try {
-            fs.unlinkSync(destPath);
-        }
-        catch { /* ignore */ }
-    }
-    try {
-        fs.mkdirSync(path.dirname(destPath), { recursive: true });
-        fs.symlinkSync(srcPath, destPath);
-    }
-    catch {
-        return false;
-    }
-    return true;
-}
 function makeScope(spec, pluginsDir, autoEnableExecSurfaces, precedence) {
     return { spec, marketplaceName: marketplaceNameFor(spec), pluginsDir, autoEnableExecSurfaces, precedence };
 }

package/dist/lib/project-resources.d.ts

@@ -0,0 +1,7 @@
+import type { AgentId } from './types.js';
+export interface ProjectResourceSyncResult {
+    synced: string[];
+    skipped: string[];
+}
+export declare function projectAgentRoot(projectRoot: string, agent: AgentId): string;
+export declare function syncProjectResourcesToAgent(agent: AgentId, version: string, projectAgentsDir: string): ProjectResourceSyncResult;