opencode-skill-autodiscovery 1.6.1 → 2.1.0

package/dist/discovery.js

@@ -1,10 +1,14 @@
-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 { log } from "./log.js";
+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 } from "./schema.js";
+import { NAME_PATTERN, PLUGIN_SCHEMA, VERSION, validateName } from "./schema.js";
 export { readAgents } from "./agents.js";
 export { readMcp } from "./mcp.js";
 function isDirectory(p) {
@@ -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;
@@ -55,19 +94,23 @@ export function readSkillInfo(dir) {
     const name = field("name");
     if (!name)
         return null;
-    return { dir, name, description: field("description") ?? "" };
+    // The description is written into config verbatim: strip ANSI escapes and
+    // C0 control characters before it can reach any config surface.
+    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
-// back to legacy discovery. The $schema URL and the manifest name are the
-// discriminators that make scanning untrusted directories safe.
-export function readPackage(root, source) {
+// back to legacy discovery. The $schema URL and the manifest name identify
+// format only — never provenance or safety: any package can copy the
+// literal schema URL. Provenance/safety is tracked separately by the
+// caller-supplied `trusted` flag.
+export function readPackage(root, source, trusted = false) {
     const manifestPath = join(root, "plugin.json");
     if (!isRegularFile(manifestPath))
         return null;
     let manifest;
     try {
-        manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        manifest = cachedRead("plugin-manifest", manifestPath, (content) => JSON.parse(content));
     }
     catch {
         return null;
@@ -77,12 +120,30 @@ export function readPackage(root, source) {
     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)) {
@@ -97,7 +158,14 @@ export function readPackage(root, source) {
             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 {
@@ -111,11 +179,14 @@ export function readPackage(root, source) {
             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,
         name: manifest.name,
         root,
         skillDirs,
@@ -123,15 +194,43 @@ export function readPackage(root, source) {
         schemaVersion: VERSION.exec(manifest.$schema)?.[1],
     };
 }
-// Legacy tree walk: every directory containing a SKILL.md, at any depth.
+// True when a discovered package matches the user's exclude list. Conformant
+// packages match on their plugin.json manifest name; legacy packages fall back
+// to the directory basename (which is what their name already is).
+function isExcluded(pkg, exclude) {
+    return exclude.includes(pkg.name);
+}
+// Belt-and-braces bound for the legacy walk. Correctness rests entirely on
+// real-path dedupe below (symlink cycles terminate because every visited path
+// is keyed on its resolved form); this cap only stops pathological deep trees
+// from exhausting the stack, and is not load-bearing for that guarantee.
+const MAX_WALK_DEPTH = 16;
+// Legacy tree walk: every directory containing a SKILL.md, down to a shallow
+// depth cap (see MAX_WALK_DEPTH). Visited and emitted paths are keyed on their
+// real (symlink-resolved) forms, so symlink cycles — self-referential or
+// ancestor-pointing — terminate the branch instead of growing ever-longer
+// lexical paths until stack exhaustion. Candidates whose real location
+// resolves outside the starting root are skipped, mirroring the containment
+// guarantee of readPackage.
 export function findSkillDirs(root, out, seen) {
-    const resolved = join(root);
-    if (seen.has(resolved))
+    let resolved;
+    try {
+        resolved = realpathSync(root);
+    }
+    catch {
+        return;
+    }
+    findSkillDirsUnder(resolved, resolved, out, seen);
+}
+function findSkillDirsUnder(realRoot, dir, out, seen, depth = 0) {
+    if (depth > MAX_WALK_DEPTH)
         return;
-    seen.add(resolved);
+    if (seen.has(dir))
+        return;
+    seen.add(dir);
     let entries;
     try {
-        entries = readdirSync(resolved);
+        entries = readdirSync(dir);
     }
     catch {
         return;
@@ -139,14 +238,30 @@ export function findSkillDirs(root, out, seen) {
     for (const entry of entries) {
         if (entry === ".git")
             continue;
-        const full = join(resolved, entry);
+        const full = join(dir, entry);
         if (!isDirectory(full))
             continue;
-        if (isRegularFile(join(full, "SKILL.md"))) {
-            out.add(full);
+        let child;
+        try {
+            child = realpathSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!contains(realRoot, child)) {
+            log(`skipping skill dir "${child}": resolves outside "${realRoot}"`);
+            continue;
+        }
+        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 {
-            findSkillDirs(full, out, seen);
+            findSkillDirsUnder(realRoot, child, out, seen, depth + 1);
         }
     }
 }
@@ -157,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;
             }
         }
@@ -184,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;
@@ -213,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;
@@ -241,40 +431,53 @@ 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;
     }
 }
+// Sanitizes the legacy directory-basename package-name fallback before it
+// feeds collision namespaces or dedupe keys: names that already satisfy
+// NAME_PATTERN pass through untouched; anything else is stripped down to
+// NAME_PATTERN-safe characters (characters outside [a-z0-9.-] removed,
+// `--`/`..` runs collapsed, edges trimmed) and rejected outright when the
+// result is empty or a prototype-chain key, falling back to a fixed safe
+// identifier. Legacy packages keep their skills even when their directory
+// name is hostile.
+function legacyFallbackName(basename) {
+    if (validateName(basename))
+        return basename;
+    const cleaned = basename
+        .replace(/[^a-z0-9.-]/g, "")
+        .replace(/-{2,}/g, "-")
+        .replace(/\.{2,}/g, ".")
+        .replace(/^[.-]+|[.-]+$/g, "");
+    return validateName(cleaned) ?? "legacy";
+}
 // Prefers a conformant package manifest; falls back to a legacy tree walk so
 // non-conformant layouts keep working. Returns null when nothing is found.
-export function packageFromDir(root, source) {
-    const pkg = readPackage(root, source);
+export function packageFromDir(root, source, trusted = false) {
+    const pkg = readPackage(root, source, trusted);
     if (pkg)
         return pkg;
     const skillDirs = new Set();
     findSkillDirs(root, skillDirs, new Set());
-    if (skillDirs.size === 0 && !hasClaudeAgents(root) && !hasFlatAgents(root)) {
+    if (skillDirs.size === 0 && !hasClaudeAgents(root) && !hasFlatAgents(root))
         return null;
-    }
     return {
         source,
-        name: root.split(/[\\/]/).pop() || root,
+        trusted,
+        name: legacyFallbackName(root.split(/[\\/]/).pop() ?? ""),
         root,
         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"),
@@ -294,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 (raw.startsWith("/"))
-        raw = raw.slice(1);
-    return raw;
+    if (!isDirectory(resolved)) {
+        log(`ignoring plugin URI "${pluginUri}": "${resolved}" is not a directory`);
+        return null;
+    }
+    return resolved;
 }
-export function collectVscodeManifest(out, installedJson) {
+export function collectVscodeManifest(out, installedJson, exclude = [], trusted = true) {
     if (!existsSync(installedJson))
         return;
     let manifest;
@@ -333,15 +563,37 @@ export function collectVscodeManifest(out, installedJson) {
     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(plugin.pluginUri);
-        if (dir) {
-            const pkg = packageFromDir(dir, "vscode");
-            if (pkg)
-                out.push(pkg);
         }
+        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 pkg = packageFromDir(dir, "vscode", trusted);
+        if (pkg && !isExcluded(pkg, exclude))
+            out.push(pkg);
     }
 }
 // Remote hosts: VS Code syncs client skills into
@@ -349,7 +601,7 @@ export function collectVscodeManifest(out, installedJson) {
 // 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) {
+export function collectVscodeCache(out, cacheJson, exclude = [], trusted = true) {
     if (!existsSync(cacheJson))
         return;
     let entries;
@@ -369,20 +621,22 @@ export function collectVscodeCache(out, cacheJson) {
         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");
-            if (pkg)
-                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");
-            if (pkg)
-                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
@@ -394,11 +648,11 @@ function sanitizeKey(value) {
         .replace(/^-|-$/g, "")
         .substring(0, 128);
 }
-function collectAgentPluginRoot(out, root) {
+function collectAgentPluginRoot(out, root, exclude = [], trusted = true) {
     const installedJson = join(root, "installed.json");
     const cacheJson = join(root, "cache.json");
-    collectVscodeManifest(out, installedJson);
-    collectVscodeCache(out, cacheJson);
+    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.
@@ -409,22 +663,23 @@ function collectAgentPluginRoot(out, root) {
     // 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");
-            if (pkg)
+        for (const pkg of findPluginPackagesCached(root, "vscode", false)) {
+            if (!isExcluded(pkg, exclude))
                 out.push(pkg);
         }
     }
 }
-export function collectVscode(out, extra) {
-    for (const dir of agentPluginDirs(vsCodeDataRoots(extra))) {
-        collectAgentPluginRoot(out, dir);
+export function collectVscode(out, extra, exclude = []) {
+    for (const { root, trusted } of agentPluginDirs(vsCodeDataRoots(extra))) {
+        collectAgentPluginRoot(out, root, exclude, trusted);
     }
 }
 // --- Claude Code plugin discovery ------------------------------------------
-export function collectClaudeManifest(out, installedJson) {
+// `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;
@@ -434,17 +689,36 @@ export function collectClaudeManifest(out, installedJson) {
     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");
-                if (pkg)
-                    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);
         }
     }
 }
-export function collectClaude(out) {
+export function collectClaude(out, exclude = []) {
     const home = homedir();
     const installedJsons = [
         join(home, ".claude", "plugins", "installed_plugins.json"),
@@ -452,24 +726,16 @@ export function collectClaude(out) {
     ];
     for (const installedJson of installedJsons) {
         if (existsSync(installedJson)) {
-            collectClaudeManifest(out, installedJson);
+            collectClaudeManifest(out, installedJson, exclude);
         }
     }
     // Always scan the SSH-synced remote bundle too: it can exist alongside a
     // local Claude Code install that has its own installed_plugins.json, and
     // the same-source mirror dedup in planConfig collapses any overlap.
-    //
-    // Like the VS Code agent plugin dir, the remote plugins root holds
-    // hash-named plugin directories with no manifest. Walk it with
-    // findPluginRoots so skills and flat agent markdown files are found by
-    // filename wherever they live — no hardcoded folder names needed.
     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");
-            if (pkg)
+        for (const pkg of findPluginPackagesCached(remoteRoot, "claude", true)) {
+            if (!isExcluded(pkg, exclude))
                 out.push(pkg);
         }
     }
@@ -483,7 +749,7 @@ export function opencodeCacheRoot() {
 // node_modules: {cache}/packages/{name}@{version}/node_modules/{name}. Scanning
 // it is what makes an npm-distributed Agent Plugins package work without any
 // manual skills.paths entry.
-export function collectOpencodeCache(packagesRoot, out) {
+export function collectOpencodeCache(packagesRoot, out, exclude = []) {
     let pkgEntries;
     try {
         pkgEntries = readdirSync(packagesRoot);
@@ -495,13 +761,14 @@ export function collectOpencodeCache(packagesRoot, out) {
         const nodeModules = join(packagesRoot, pkgEntry, "node_modules");
         if (!isDirectory(nodeModules))
             continue;
-        collectNodeModules(nodeModules, out);
+        // opencode installed these packages itself, so they are deliberate.
+        collectNodeModules(nodeModules, out, true, exclude);
     }
 }
 // Enumerates immediate package roots of a node_modules dir, including scoped
 // packages (@scope/*). Only conformant packages (root plugin.json) are read;
 // nothing else is walked.
-export function collectNodeModules(nodeModulesRoot, out) {
+export function collectNodeModules(nodeModulesRoot, out, trusted = false, exclude = []) {
     if (!isDirectory(nodeModulesRoot))
         return;
     let entries;
@@ -528,14 +795,14 @@ export function collectNodeModules(nodeModulesRoot, out) {
             for (const sub of scoped) {
                 if (sub.startsWith("."))
                     continue;
-                const pkg = readPackage(join(candidate, sub), "node_modules");
-                if (pkg)
+                const pkg = readPackage(join(candidate, sub), "node_modules", trusted);
+                if (pkg && !isExcluded(pkg, exclude))
                     out.push(pkg);
             }
         }
         else {
-            const pkg = readPackage(candidate, "node_modules");
-            if (pkg)
+            const pkg = readPackage(candidate, "node_modules", trusted);
+            if (pkg && !isExcluded(pkg, exclude))
                 out.push(pkg);
         }
     }
@@ -564,16 +831,34 @@ function dedupePackages(packages) {
 // namespaced by package name, and MCP servers keyed by server name with
 // collisions namespaced by package name. `taken` seeds the reserved names from
 // the user's existing config so user-defined entries are never overwritten.
-export function planConfig(packages, taken = {}) {
+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 = {}, 
+// 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 = [];
@@ -591,6 +876,12 @@ export function planConfig(packages, taken = {}) {
             if (!info)
                 continue;
             let name = info.name;
+            // SKILL.md frontmatter is package-supplied input: gate the name before
+            // it becomes any config key (applyConfigPatch writes config.command[name]).
+            if (!validateName(name)) {
+                log(`skipping skill frontmatter for package "${pkg.name}": invalid name "${name}" (must match the identifier pattern and not be a prototype-chain key)`);
+                continue;
+            }
             const owner = commandOwner.get(name);
             if (owner !== undefined) {
                 if (owner === pkg.source) {
@@ -611,73 +902,121 @@ export function planConfig(packages, taken = {}) {
                 name,
                 description: info.description || `Run the ${info.name} skill`,
                 template: [
-                    `Load the \`${info.name}\` skill and follow its instructions.`,
+                    // The name is a quoted data value (JSON string encoding), never
+                    // wrapped in backticks: even a name that skipped validateName
+                    // cannot terminate the quote and inject template text.
+                    `Load the ${JSON.stringify(info.name)} skill and follow its instructions.`,
                     `Context: $ARGUMENTS`,
                 ].join("\n"),
+                trusted: pkg.trusted,
             });
         }
     }
     const 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) {
-        const entries = [];
-        readMcp(pkg, entries);
-        for (const { key, entry } of entries) {
-            const dedupeKey = `${pkg.root}\u0000${key}`;
-            if (seenMcpEntry.has(dedupeKey))
+    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;
-            seenMcpEntry.add(dedupeKey);
-            let k = key;
-            const owner = mcpOwner.get(k);
-            if (owner !== undefined) {
-                if (owner === pkg.source)
-                    continue;
-                const namespaced = `${pkg.name}/${key}`;
-                if (usedMcp.has(namespaced)) {
-                    log(`skipping MCP server "${pkg.name}/${key}": name already taken`);
+            }
+            const entries = [];
+            readMcp(pkg, entries);
+            for (const { key, entry } of entries) {
+                const dedupeKey = `${pkg.root}\u0000${key}`;
+                if (seenMcpEntry.has(dedupeKey))
                     continue;
+                seenMcpEntry.add(dedupeKey);
+                let k = key;
+                const owner = mcpOwner.get(k);
+                if (owner !== undefined) {
+                    if (owner === pkg.source)
+                        continue;
+                    const namespaced = `${pkg.name}/${key}`;
+                    if (usedMcp.has(namespaced)) {
+                        log(`skipping MCP server "${pkg.name}/${key}": name already taken`);
+                        continue;
+                    }
+                    k = namespaced;
                 }
-                k = namespaced;
+                mcpOwner.set(k, pkg.source);
+                usedMcp.add(k);
+                mcp.push({ key: k, entry, trusted: pkg.trusted });
             }
-            mcpOwner.set(k, pkg.source);
-            usedMcp.add(k);
-            mcp.push({ key: k, entry });
         }
     }
     const 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)) {
-            const dedupeKey = `${pkg.root}\u0000${name}`;
-            if (seenAgent.has(dedupeKey))
+    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) {
+            // 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;
-            seenAgent.add(dedupeKey);
-            let agentName = name;
-            const owner = agentOwner.get(agentName);
-            if (owner !== undefined) {
-                if (owner === pkg.source)
-                    continue;
-                const namespaced = `${pkg.name}-${agentName}`;
-                if (usedAgents.has(namespaced)) {
-                    log(`skipping agent "${pkg.name}/${agentName}": name already taken`);
+            }
+            for (const { name, agent } of pkgAgents) {
+                const dedupeKey = `${pkg.root}\u0000${name}`;
+                if (seenAgent.has(dedupeKey))
                     continue;
+                seenAgent.add(dedupeKey);
+                let agentName = name;
+                const owner = agentOwner.get(agentName);
+                if (owner !== undefined) {
+                    if (owner === pkg.source)
+                        continue;
+                    const namespaced = `${pkg.name}-${agentName}`;
+                    if (usedAgents.has(namespaced)) {
+                        log(`skipping agent "${pkg.name}/${agentName}": name already taken`);
+                        continue;
+                    }
+                    agentName = namespaced;
                 }
-                agentName = namespaced;
+                agentOwner.set(agentName, pkg.source);
+                usedAgents.add(agentName);
+                agents.push({ name: agentName, agent, trusted: pkg.trusted });
             }
-            agentOwner.set(agentName, pkg.source);
-            usedAgents.add(agentName);
-            agents.push({ name: agentName, agent });
         }
     }
-    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.
@@ -699,7 +1038,10 @@ export function applyConfigPatch(config, plan, enabled) {
         }
     }
     if (plan.commands.length > 0) {
-        config.command ??= {};
+        // Containers are built prototype-free so a key can never resolve to an
+        // inherited member (__proto__/constructor/toString), even if a future
+        // call site skips the upstream validateName gate.
+        config.command ??= Object.create(null);
         for (const cmd of plan.commands) {
             if (config.command[cmd.name])
                 continue;
@@ -710,15 +1052,26 @@ export function applyConfigPatch(config, plan, enabled) {
         }
     }
     if (enabled.mcp && plan.mcp.length > 0) {
-        config.mcp ??= {};
+        config.mcp ??= Object.create(null);
         for (const { key, entry } of plan.mcp) {
             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) {
-        config.agent ??= {};
+        config.agent ??= Object.create(null);
         for (const { name, agent } of plan.agents) {
             if (config.agent[name])
                 continue;