opencode-skill-autodiscovery 2.0.0 → 2.1.0

package/dist/discovery.js

@@ -1,7 +1,11 @@
-import { existsSync, readFileSync, readdirSync, realpathSync, statSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cachedRead } from "./cache.js";
+import { getCachedPackages, setCachedPackages, fingerprintTree } from "./discovery-cache.js";
 import { log, sanitize } from "./log.js";
+import { PLUGIN_SCHEMA_1_0_0_ID, validatePluginManifest } from "./spec-schema.js";
 import { readAgents } from "./agents.js";
 import { readMcp } from "./mcp.js";
 import { NAME_PATTERN, PLUGIN_SCHEMA, VERSION, validateName } from "./schema.js";
@@ -23,6 +27,16 @@ function isRegularFile(p) {
         return false;
     }
 }
+// True only for a JSON object container: not null, not an array, and not some
+// other object kind. Manifest inputs are parsed JSON, so this rejects every
+// shape other than a plain object before its keys are iterated.
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
 // True when `child` resolves (through symlinks) inside `parent`.
 export function contains(parent, child) {
     const p = realpathSync(parent);
@@ -32,17 +46,42 @@ export function contains(parent, child) {
     const rel = relative(p, c);
     return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
 }
+// Resolves `candidate` to its real path and returns it only when it still
+// lives inside `root` (through symlinks); returns null when it is missing or
+// escapes. This is the read gate for package files whose bytes feed config:
+// a package must not be able to ship a symlink (mcp.json, AGENTS.md, a flat
+// agent .md) that reads a file it never contained. A rejected candidate is
+// logged once, naming the package root and the outside target.
+export function resolveContained(root, candidate) {
+    let resolved;
+    try {
+        resolved = realpathSync(candidate);
+    }
+    catch {
+        return null;
+    }
+    if (!contains(root, resolved)) {
+        log(`skipping "${resolved}": resolves outside "${root}"`);
+        return null;
+    }
+    return resolved;
+}
 // Parses the YAML frontmatter of a SKILL.md (name, description). Returns null
 // when the file is unreadable or lacks a valid `name`.
 export function readSkillInfo(dir) {
     const skillMd = join(dir, "SKILL.md");
-    let content;
+    let parsed;
     try {
-        content = readFileSync(skillMd, "utf8");
+        parsed = cachedRead("skill-frontmatter", skillMd, parseSkillFrontmatter);
     }
     catch {
         return null;
     }
+    if (!parsed)
+        return null;
+    return { dir, name: parsed.name, description: parsed.description };
+}
+function parseSkillFrontmatter(content) {
     const frontmatter = /^---\s*\n([\s\S]*?)\n---/.exec(content)?.[1];
     if (!frontmatter)
         return null;
@@ -57,7 +96,7 @@ export function readSkillInfo(dir) {
         return null;
     // The description is written into config verbatim: strip ANSI escapes and
     // C0 control characters before it can reach any config surface.
-    return { dir, name, description: sanitize(field("description") ?? "") };
+    return { name, description: sanitize(field("description") ?? "") };
 }
 // Reads a conformant Agent Plugins 1.0.0 package from a directory root.
 // Returns null when the root has no valid plugin.json, so callers can fall
@@ -71,7 +110,7 @@ export function readPackage(root, source, trusted = false) {
         return null;
     let manifest;
     try {
-        manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        manifest = cachedRead("plugin-manifest", manifestPath, (content) => JSON.parse(content));
     }
     catch {
         return null;
@@ -81,12 +120,30 @@ export function readPackage(root, source, trusted = false) {
     if (typeof manifest.$schema !== "string" || !PLUGIN_SCHEMA.test(manifest.$schema)) {
         return null;
     }
-    if (typeof manifest.name !== "string" ||
+    // Rigorous structural validation against the real published schema, when
+    // this plugin has vendored a copy matching the declared version (today,
+    // only 1.0.0). Any other conformant 1.x.x version falls back to the
+    // name-only check below, so a future minor version is never rejected just
+    // because this plugin hasn't vendored its schema yet — see spec-schema.ts.
+    if (manifest.$schema === PLUGIN_SCHEMA_1_0_0_ID) {
+        const result = validatePluginManifest(manifest);
+        if (!result.valid) {
+            log(`ignoring plugin.json at "${root}": fails Agent Plugins 1.0.0 schema (${result.errors.join("; ")})`);
+            return null;
+        }
+    }
+    else if (typeof manifest.name !== "string" ||
         manifest.name.length === 0 ||
         manifest.name.length > 64 ||
         !NAME_PATTERN.test(manifest.name)) {
         return null;
     }
+    // Narrows `manifest.name` for TS: always true here (either branch above
+    // already guarantees it — ajv's `name` schema requires a string, the
+    // fallback branch checked it directly) but ajv validation doesn't carry
+    // type-level narrowing the way the explicit typeof check does.
+    if (typeof manifest.name !== "string")
+        return null;
     const skillDirs = [];
     const skillsRoot = join(root, "skills");
     if (isDirectory(skillsRoot)) {
@@ -101,7 +158,14 @@ export function readPackage(root, source, trusted = false) {
             const dir = join(skillsRoot, entry);
             if (!isDirectory(dir))
                 continue;
-            if (!isRegularFile(join(dir, "SKILL.md")))
+            const skillMd = join(dir, "SKILL.md");
+            if (!isRegularFile(skillMd))
+                continue;
+            // The directory alone is not enough: a package can keep the skill dir
+            // in-root while symlinking its SKILL.md to an outside file, whose bytes
+            // would otherwise become prompt material. Require the skill file itself
+            // to resolve inside the package too.
+            if (!resolveContained(root, skillMd))
                 continue;
             let resolved;
             try {
@@ -115,9 +179,11 @@ export function readPackage(root, source, trusted = false) {
             skillDirs.push(resolved);
         }
     }
-    const mcpPath = isRegularFile(join(root, "mcp.json"))
-        ? join(root, "mcp.json")
-        : undefined;
+    // mcp.json is package-supplied input read into config.mcp: resolve it
+    // through the containment gate first, so a symlink cannot point it at a
+    // file outside the package.
+    const mcpResolved = resolveContained(root, join(root, "mcp.json"));
+    const mcpPath = mcpResolved && isRegularFile(mcpResolved) ? mcpResolved : undefined;
     return {
         source,
         trusted,
@@ -186,7 +252,12 @@ function findSkillDirsUnder(realRoot, dir, out, seen, depth = 0) {
             log(`skipping skill dir "${child}": resolves outside "${realRoot}"`);
             continue;
         }
-        if (isRegularFile(join(child, "SKILL.md"))) {
+        const childSkillMd = join(child, "SKILL.md");
+        if (isRegularFile(childSkillMd)) {
+            // A skill dir whose SKILL.md symlinks outside the walk root must not be
+            // emitted: readSkillInfo (and opencode) would read the outside bytes.
+            if (!resolveContained(realRoot, childSkillMd))
+                continue;
             out.add(child);
         }
         else {
@@ -201,7 +272,10 @@ function hasPluginLayout(root) {
     const skillsRoot = join(root, "skills");
     if (isDirectory(skillsRoot)) {
         try {
-            if (readdirSync(skillsRoot).some((e) => isRegularFile(join(skillsRoot, e, "SKILL.md")))) {
+            if (readdirSync(skillsRoot).some((e) => {
+                const skillMd = join(skillsRoot, e, "SKILL.md");
+                return resolveContained(root, skillMd) !== null && isRegularFile(skillMd);
+            })) {
                 return true;
             }
         }
@@ -228,28 +302,86 @@ function hasRootAgentFiles(root) {
     return entries.some((e) => {
         if (!e.endsWith(".md"))
             return false;
-        const full = join(root, e);
-        if (!isRegularFile(full))
+        const contained = resolveContained(root, join(root, e));
+        if (!contained || !isRegularFile(contained))
             return false;
-        const m = /^---\s*\n([\s\S]*?)\n---/.exec(readFileSync(full, "utf8"))?.[1];
-        if (!m)
+        try {
+            return cachedRead("agent-frontmatter-check", contained, hasAgentFrontmatter);
+        }
+        catch {
             return false;
-        return /^name:[ \t]/.test(m) || /^description:[ \t]/.test(m);
+        }
     });
 }
+function hasAgentFrontmatter(content) {
+    const m = /^---\s*\n([\s\S]*?)\n---/.exec(content)?.[1];
+    if (!m)
+        return false;
+    return /^name:[ \t]/.test(m) || /^description:[ \t]/.test(m);
+}
 // Returns directories under `root` that are individual plugin roots. This
 // mirrors what VS Code's installed.json points at (each {host}/{org}/{repo}
 // clone, and inside a marketplace like agency-agents each
 // ref_plugins/plugins/<division> dir), so a clone on disk is registered
 // per-plugin instead of as one opaque tree that hides its agents.
+//
+// Hardened like findSkillDirs: traversal and emitted roots are keyed on real
+// (symlink-resolved) paths, so symlink cycles — self-referential or
+// ancestor-pointing — terminate instead of growing ever-longer lexical paths
+// until stack exhaustion, and nothing that resolves outside the starting root
+// is emitted. `isDirectory` uses statSync, which follows symlinks, so the
+// realpath dedupe below is what bounds the walk.
 export function findPluginRoots(root, out) {
-    if (hasPluginLayout(root)) {
-        out.push(root);
+    let resolved;
+    try {
+        resolved = realpathSync(root);
+    }
+    catch {
+        return;
+    }
+    findPluginRootsUnder(resolved, resolved, out, new Set());
+}
+// Equivalent to a caller doing `findPluginRoots(root, roots)` and converting
+// each hit with `packageFromDir(pluginRoot, source, trusted)` — the exact
+// pattern collectAgentPluginRoot's fallback and collectClaude's remote walk
+// both used before discovery-cache.ts existed — except a cheap fingerprint
+// check of `root` (see fingerprintTree) can skip the real walk, and every
+// file read inside it, entirely when the subtree hasn't changed since the
+// last run. A miss falls back to exactly the walk+convert callers did
+// before, so this is never slower than the un-cached baseline.
+//
+// `exclude` is deliberately the caller's job, applied identically on a hit
+// or a miss, so changing the exclude list never has to invalidate the cache.
+function findPluginPackagesCached(root, source, trusted) {
+    const fingerprint = fingerprintTree(root);
+    const key = JSON.stringify([source, root]);
+    const cached = getCachedPackages(key, fingerprint);
+    if (cached)
+        return cached;
+    const roots = [];
+    findPluginRoots(root, roots);
+    const packages = [];
+    for (const pluginRoot of roots) {
+        const pkg = packageFromDir(pluginRoot, source, trusted);
+        if (pkg)
+            packages.push(pkg);
+    }
+    setCachedPackages(key, fingerprint, packages);
+    return packages;
+}
+function findPluginRootsUnder(realRoot, dir, out, seen, depth = 0) {
+    if (depth > MAX_WALK_DEPTH)
+        return;
+    if (seen.has(dir))
+        return;
+    seen.add(dir);
+    if (hasPluginLayout(dir)) {
+        out.push(dir);
         return;
     }
     let entries;
     try {
-        entries = readdirSync(root);
+        entries = readdirSync(dir);
     }
     catch {
         return;
@@ -257,17 +389,31 @@ export function findPluginRoots(root, out) {
     for (const entry of entries) {
         if (entry === ".git" || entry === "node_modules")
             continue;
-        const full = join(root, entry);
+        const full = join(dir, entry);
         if (!isDirectory(full))
             continue;
-        findPluginRoots(full, out);
+        let child;
+        try {
+            child = realpathSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!contains(realRoot, child)) {
+            log(`skipping plugin dir "${child}": resolves outside "${realRoot}"`);
+            continue;
+        }
+        findPluginRootsUnder(realRoot, child, out, seen, depth + 1);
     }
 }
 // True when a legacy Claude Code plugin declares at least one agent, so an
 // agents-only plugin is still discovered even though it ships no skills.
 function hasClaudeAgents(root) {
+    const manifestPath = resolveContained(root, join(root, ".claude-plugin", "plugin.json"));
+    if (!manifestPath)
+        return false;
     try {
-        const manifest = JSON.parse(readFileSync(join(root, ".claude-plugin", "plugin.json"), "utf8"));
+        const manifest = cachedRead("claude-legacy-manifest", manifestPath, (content) => JSON.parse(content));
         if (typeof manifest !== "object" || manifest === null)
             return false;
         const agents = manifest.agents;
@@ -285,8 +431,9 @@ function hasClaudeAgents(root) {
 function hasFlatAgents(root) {
     if (hasRootAgentFiles(root))
         return true;
+    const agentsDir = join(root, "agents");
     try {
-        return readdirSync(join(root, "agents")).some((e) => e.endsWith(".md"));
+        return readdirSync(agentsDir).some((e) => e.endsWith(".md") && resolveContained(root, join(agentsDir, e)) !== null);
     }
     catch {
         return false;
@@ -328,15 +475,9 @@ export function packageFromDir(root, source, trusted = false) {
         skillDirs: [...skillDirs],
     };
 }
-// --- VS Code agent plugin discovery ---------------------------------------
-// VS Code keeps agent plugins in a per-platform "data dir". The holding
-// folder is named `agent-plugins` on older builds (e.g. ~/.vscode) and
-// `agentPlugins` on newer builds; remote servers nest theirs under `data/`
-// (~/.vscode-server/data/agentPlugins). We list every known candidate so the
-// discovery works regardless of OS, build channel, or local/remote setup.
 function vsCodeDataRoots(extra) {
     const home = homedir();
-    const roots = new Set([
+    const builtIn = new Set([
         join(home, ".vscode"),
         // Linux
         join(home, ".config", "Code"),
@@ -356,36 +497,63 @@ function vsCodeDataRoots(extra) {
         join(home, ".vscode-server-insiders"),
         join(home, ".vscode-remote"),
     ]);
-    for (const root of extra)
-        roots.add(root);
-    return [...roots];
+    const roots = [...builtIn].map((root) => ({ root, trusted: true }));
+    const seen = new Set(builtIn);
+    for (const root of extra) {
+        if (seen.has(root))
+            continue;
+        seen.add(root);
+        roots.push({ root, trusted: false });
+    }
+    return roots;
 }
 function agentPluginDirs(roots) {
-    const dirs = new Set();
-    for (const root of roots) {
-        dirs.add(join(root, "agent-plugins"));
-        dirs.add(join(root, "agentPlugins"));
-        dirs.add(join(root, "data", "agent-plugins"));
-        dirs.add(join(root, "data", "agentPlugins"));
+    const seen = new Set();
+    const dirs = [];
+    for (const { root, trusted } of roots) {
+        for (const dir of [
+            join(root, "agent-plugins"),
+            join(root, "agentPlugins"),
+            join(root, "data", "agent-plugins"),
+            join(root, "data", "agentPlugins"),
+        ]) {
+            if (seen.has(dir))
+                continue;
+            seen.add(dir);
+            dirs.push({ root: dir, trusted });
+        }
     }
-    return [...dirs];
+    return dirs;
 }
+// Resolves an `installed.json` `pluginUri` to an on-disk plugin root. Only
+// `file:` URLs name a local directory: non-file schemes and malformed URLs are
+// dropped (with a log) rather than echoed into the filesystem, and the
+// resolved target must be an existing directory. `fileURLToPath` owns the
+// slash/percent/drive-letter normalization; `resolve` then canonicalizes the
+// result so a technically valid URL like `file:////abs` yields the same root
+// string as its `file:///abs` spelling.
 function vscodePluginPath(pluginUri) {
-    const m = /^file:\/\/(.+)$/.exec(pluginUri);
-    if (!m)
-        return pluginUri;
-    let raw;
+    let resolved;
     try {
-        raw = decodeURIComponent(m[1]);
+        resolved = resolve(fileURLToPath(pluginUri));
     }
     catch {
-        raw = m[1];
+        log(`ignoring plugin URI "${pluginUri}": not a resolvable file: URL`);
+        return null;
+    }
+    // `file://` (and `file:///`) resolve to the filesystem root; a plugin root
+    // is never the root itself, and walking it would scan the whole disk.
+    if (dirname(resolved) === resolved) {
+        log(`ignoring plugin URI "${pluginUri}": filesystem root is not a plugin root`);
+        return null;
+    }
+    if (!isDirectory(resolved)) {
+        log(`ignoring plugin URI "${pluginUri}": "${resolved}" is not a directory`);
+        return null;
     }
-    if (raw.startsWith("/"))
-        raw = raw.slice(1);
-    return raw;
+    return resolved;
 }
-export function collectVscodeManifest(out, installedJson, exclude = []) {
+export function collectVscodeManifest(out, installedJson, exclude = [], trusted = true) {
     if (!existsSync(installedJson))
         return;
     let manifest;
@@ -395,15 +563,37 @@ export function collectVscodeManifest(out, installedJson, exclude = []) {
     catch {
         return;
     }
-    for (const plugin of manifest.installed ?? []) {
-        if (!plugin.pluginUri)
+    // installed.json is manifest input: fail closed on a malformed shape rather
+    // than iterating a non-array (which throws) or trusting entry types.
+    const installed = isPlainObject(manifest) ? manifest.installed : undefined;
+    if (!Array.isArray(installed)) {
+        log(`ignoring "${installedJson}": "installed" is not an array`);
+        return;
+    }
+    const root = dirname(installedJson);
+    for (const plugin of installed) {
+        if (!isPlainObject(plugin)) {
+            log(`ignoring entry in "${installedJson}": entry is not an object`);
+            continue;
+        }
+        const pluginUri = plugin.pluginUri;
+        if (typeof pluginUri !== "string") {
+            log(`ignoring entry in "${installedJson}": "pluginUri" is not a string`);
+            continue;
+        }
+        const dir = vscodePluginPath(pluginUri);
+        if (!dir)
+            continue;
+        // installed.json is manifest input: under an untrusted root the recorded
+        // install location must resolve inside that root. A trusted home root is
+        // allowed to point at a global extension directory outside the data root.
+        if (!trusted && !contains(root, dir)) {
+            log(`skipping plugin URI "${pluginUri}": "${dir}" is outside untrusted root "${root}"`);
             continue;
-        const dir = vscodePluginPath(plugin.pluginUri);
-        if (dir) {
-            const pkg = packageFromDir(dir, "vscode", true);
-            if (pkg && !isExcluded(pkg, exclude))
-                out.push(pkg);
         }
+        const pkg = packageFromDir(dir, "vscode", trusted);
+        if (pkg && !isExcluded(pkg, exclude))
+            out.push(pkg);
     }
 }
 // Remote hosts: VS Code syncs client skills into
@@ -411,7 +601,7 @@ export function collectVscodeManifest(out, installedJson, exclude = []) {
 // cache.json. Resolve each entry so the materialized synced-customization
 // bundle ("VS Code Synced Data" Open Plugin, skills/<name>/SKILL.md) is
 // discovered.
-export function collectVscodeCache(out, cacheJson, exclude = []) {
+export function collectVscodeCache(out, cacheJson, exclude = [], trusted = true) {
     if (!existsSync(cacheJson))
         return;
     let entries;
@@ -431,20 +621,22 @@ export function collectVscodeCache(out, cacheJson, exclude = []) {
         const nonce = typeof entry.nonce === "string" && entry.nonce
             ? sanitizeKey(entry.nonce)
             : "default";
+        // Layouts without the {nonce} subdirectory materialize the bundle
+        // directly under {key}; falling back only when the nonce dir is absent
+        // avoids re-descending into it.
         const nonceDir = join(parent, key, nonce);
-        if (isDirectory(nonceDir)) {
-            const pkg = packageFromDir(nonceDir, "vscode", true);
-            if (pkg && !isExcluded(pkg, exclude))
-                out.push(pkg);
-        }
-        else {
-            // Layouts without the {nonce} subdirectory materialize the bundle
-            // directly under {key}; walking it only when the nonce dir is absent
-            // avoids re-descending into it.
-            const pkg = packageFromDir(join(parent, key), "vscode", true);
-            if (pkg && !isExcluded(pkg, exclude))
-                out.push(pkg);
+        const dir = isDirectory(nonceDir) ? nonceDir : join(parent, key);
+        if (!isDirectory(dir))
+            continue;
+        // cache.json is manifest input: under an untrusted root the bundle must
+        // resolve inside that root, not be redirected elsewhere on disk.
+        if (!trusted && !contains(parent, dir)) {
+            log(`skipping cache entry "${entry.uri}": "${dir}" is outside untrusted root "${parent}"`);
+            continue;
         }
+        const pkg = packageFromDir(dir, "vscode", trusted);
+        if (pkg && !isExcluded(pkg, exclude))
+            out.push(pkg);
     }
 }
 // Mirrors the server-side AgentPluginManager sanitizer so we can resolve the
@@ -456,11 +648,11 @@ function sanitizeKey(value) {
         .replace(/^-|-$/g, "")
         .substring(0, 128);
 }
-function collectAgentPluginRoot(out, root, exclude = []) {
+function collectAgentPluginRoot(out, root, exclude = [], trusted = true) {
     const installedJson = join(root, "installed.json");
     const cacheJson = join(root, "cache.json");
-    collectVscodeManifest(out, installedJson, exclude);
-    collectVscodeCache(out, cacheJson, exclude);
+    collectVscodeManifest(out, installedJson, exclude, trusted);
+    collectVscodeCache(out, cacheJson, exclude, trusted);
     // `installed.json` is the authoritative record of what VS Code installed;
     // when it exists, respect it exactly and skip the fallback walk so
     // cloned-but-not-installed marketplaces stay hidden.
@@ -471,22 +663,23 @@ function collectAgentPluginRoot(out, root, exclude = []) {
     // clone) has no manifest entry at all. Only suppress the walk when
     // installed.json exists, so any clone actually on disk is still discovered.
     if (!existsSync(installedJson)) {
-        const pluginRoots = [];
-        findPluginRoots(root, pluginRoots);
-        for (const pluginRoot of pluginRoots) {
-            const pkg = packageFromDir(pluginRoot, "vscode", false);
-            if (pkg && !isExcluded(pkg, exclude))
+        for (const pkg of findPluginPackagesCached(root, "vscode", false)) {
+            if (!isExcluded(pkg, exclude))
                 out.push(pkg);
         }
     }
 }
 export function collectVscode(out, extra, exclude = []) {
-    for (const dir of agentPluginDirs(vsCodeDataRoots(extra))) {
-        collectAgentPluginRoot(out, dir, exclude);
+    for (const { root, trusted } of agentPluginDirs(vsCodeDataRoots(extra))) {
+        collectAgentPluginRoot(out, root, exclude, trusted);
     }
 }
 // --- Claude Code plugin discovery ------------------------------------------
-export function collectClaudeManifest(out, installedJson, exclude = []) {
+// `trusted` defaults to true: every Claude root is home-scoped and
+// host-managed (`~/.claude/...`), so it stays trusted. The parameter exists
+// for symmetry with the VS Code collectors, letting a caller mark a non-home
+// manifest untrusted.
+export function collectClaudeManifest(out, installedJson, exclude = [], trusted = true) {
     if (!existsSync(installedJson))
         return;
     let manifest;
@@ -496,13 +689,32 @@ export function collectClaudeManifest(out, installedJson, exclude = []) {
     catch {
         return;
     }
-    for (const versions of Object.values(manifest.plugins ?? {})) {
+    // installed_plugins.json is manifest input: fail closed when `plugins` is not
+    // a plain object, when a version bucket is not an array, or when an entry
+    // lacks a string installPath.
+    const plugins = isPlainObject(manifest) ? manifest.plugins : undefined;
+    if (!isPlainObject(plugins)) {
+        log(`ignoring "${installedJson}": "plugins" is not an object`);
+        return;
+    }
+    for (const versions of Object.values(plugins)) {
+        if (!Array.isArray(versions)) {
+            log(`ignoring entry in "${installedJson}": plugin versions are not an array`);
+            continue;
+        }
         for (const plugin of versions) {
-            if (plugin.installPath) {
-                const pkg = packageFromDir(plugin.installPath, "claude", true);
-                if (pkg && !isExcluded(pkg, exclude))
-                    out.push(pkg);
+            if (!isPlainObject(plugin)) {
+                log(`ignoring entry in "${installedJson}": entry is not an object`);
+                continue;
             }
+            const installPath = plugin.installPath;
+            if (typeof installPath !== "string") {
+                log(`ignoring entry in "${installedJson}": "installPath" is not a string`);
+                continue;
+            }
+            const pkg = packageFromDir(installPath, "claude", trusted);
+            if (pkg && !isExcluded(pkg, exclude))
+                out.push(pkg);
         }
     }
 }
@@ -522,11 +734,8 @@ export function collectClaude(out, exclude = []) {
     // the same-source mirror dedup in planConfig collapses any overlap.
     const remoteRoot = join(home, ".claude", "remote", "plugins");
     if (existsSync(remoteRoot)) {
-        const roots = [];
-        findPluginRoots(remoteRoot, roots);
-        for (const pluginRoot of roots) {
-            const pkg = packageFromDir(pluginRoot, "claude", true);
-            if (pkg && !isExcluded(pkg, exclude))
+        for (const pkg of findPluginPackagesCached(remoteRoot, "claude", true)) {
+            if (!isExcluded(pkg, exclude))
                 out.push(pkg);
         }
     }
@@ -626,16 +835,30 @@ export function planConfig(packages, taken = {},
 // Mirrors the plugin options: when mcp is false the MCP subsystem is
 // skipped entirely — no mcp.json parsing, no filesystem side effects.
 // Same for agents: when agents is false readAgents is never invoked.
-enabled = {}) {
+enabled = {}, 
+// Per-package consent for untrusted packages: a package discovered as a
+// side effect contributes nothing to plan.mcp or plan.agents unless its
+// name is listed in the matching consent list.
+consent = {}) {
     packages = dedupePackages(packages);
     const skillPaths = [];
+    const skillTrust = [];
     const seenDir = new Set();
     for (const pkg of packages) {
+        // Graduated default, permissive half: skills and slash commands are
+        // read-only content registration and stay allowed for every trust tier —
+        // surfacing them is the plugin's job. An untrusted package registers
+        // exactly like a trusted one, but emits one info line so side-effect
+        // content entering the session stays visible to the user.
+        if (!pkg.trusted && pkg.skillDirs.length > 0) {
+            log(`registering skills and slash commands for untrusted package "${pkg.name}" (${pkg.source})`);
+        }
         for (const dir of pkg.skillDirs) {
             if (seenDir.has(dir))
                 continue;
             seenDir.add(dir);
             skillPaths.push(dir);
+            skillTrust.push({ dir, trusted: pkg.trusted });
         }
     }
     const commands = [];
@@ -685,17 +908,44 @@ enabled = {}) {
                     `Load the ${JSON.stringify(info.name)} skill and follow its instructions.`,
                     `Context: $ARGUMENTS`,
                 ].join("\n"),
+                trusted: pkg.trusted,
             });
         }
     }
     const mcp = [];
     if (enabled.mcp !== false) {
+        const consentedMcp = new Set(consent.mcp ?? []);
         const usedMcp = new Set(taken.mcp ?? []);
         const mcpOwner = new Map();
         for (const name of taken.mcp ?? [])
             mcpOwner.set(name, "user");
         const seenMcpEntry = new Set();
         for (const pkg of packages) {
+            // Trust gate: MCP servers are both powerful and opaque to opencode.
+            // Untrusted packages are present merely as side effects, so they never
+            // contribute servers unless the user consented to the package by name.
+            // Host-vouched installs (trusted: true) pass through unchanged.
+            if (!pkg.trusted && !consentedMcp.has(pkg.name)) {
+                // Slice the credential signal out of the untrusted package's mcp.json
+                // so entries carrying headers/env/url credentials get a per-entry
+                // refusal line. readMcp runs with warnings off: a refused credential
+                // must never be told it "will be stored in opencode's config".
+                if (pkg.mcpPath) {
+                    const entries = [];
+                    readMcp(pkg, entries, { warn: false });
+                    let named = 0;
+                    for (const { key, credentialReason } of entries) {
+                        if (!credentialReason)
+                            continue;
+                        named++;
+                        log(`skipping MCP server "${pkg.name}/${key}" (${pkg.source}): ${credentialReason}; add it to consent.mcp to admit its servers`);
+                    }
+                    if (named === 0) {
+                        log(`skipping MCP server for untrusted package "${pkg.name}" (${pkg.source}): add it to consent.mcp to admit its servers`);
+                    }
+                }
+                continue;
+            }
             const entries = [];
             readMcp(pkg, entries);
             for (const { key, entry } of entries) {
@@ -717,19 +967,33 @@ enabled = {}) {
                 }
                 mcpOwner.set(k, pkg.source);
                 usedMcp.add(k);
-                mcp.push({ key: k, entry });
+                mcp.push({ key: k, entry, trusted: pkg.trusted });
             }
         }
     }
     const agents = [];
     if (enabled.agents !== false) {
+        const consentedAgents = new Set(consent.agents ?? []);
         const usedAgents = new Set(taken.agents ?? []);
         const agentOwner = new Map();
         for (const name of taken.agents ?? [])
             agentOwner.set(name, "user");
         const seenAgent = new Set();
         for (const pkg of packages) {
-            for (const { name, agent } of readAgents(pkg)) {
+            // Trust gate: agents are prompt-and-behavior material that a package
+            // registers into opencode config slots. Untrusted packages are present
+            // merely as side effects, so they contribute agents only when the user
+            // consented to the package by name. Host-vouched installs (trusted:
+            // true) pass through. Note the readAgents call is hoisted so name
+            // validation logs behave identically for every admitted package.
+            const pkgAgents = readAgents(pkg);
+            if (!pkg.trusted && !consentedAgents.has(pkg.name)) {
+                if (pkgAgents.length > 0) {
+                    log(`skipping agents for untrusted package "${pkg.name}" (${pkg.source}): add it to consent.agents to admit its agents`);
+                }
+                continue;
+            }
+            for (const { name, agent } of pkgAgents) {
                 const dedupeKey = `${pkg.root}\u0000${name}`;
                 if (seenAgent.has(dedupeKey))
                     continue;
@@ -748,11 +1012,11 @@ enabled = {}) {
                 }
                 agentOwner.set(agentName, pkg.source);
                 usedAgents.add(agentName);
-                agents.push({ name: agentName, agent });
+                agents.push({ name: agentName, agent, trusted: pkg.trusted });
             }
         }
     }
-    return { skillPaths, commands, mcp, agents };
+    return { skillPaths, skillTrust, commands, mcp, agents };
 }
 // Applies a computed plan to the resolved config. Never overwrites user-defined
 // entries; de-duplicates paths against what the user already configured.
@@ -793,6 +1057,17 @@ export function applyConfigPatch(config, plan, enabled) {
             if (config.mcp[key])
                 continue;
             config.mcp[key] = entry;
+            // A package stdio server runs with PLUGIN_DATA pointing at its data
+            // dir. The dir is created only here, when the server is actually
+            // applied -- never at plan time, so planning leaves no trace on disk.
+            if (entry.type === "local" && entry.environment?.PLUGIN_DATA) {
+                try {
+                    mkdirSync(entry.environment.PLUGIN_DATA, { recursive: true });
+                }
+                catch {
+                    // Non-fatal: the subprocess env still points at the (uncreated) dir.
+                }
+            }
         }
     }
     if (doAgents) {