@chatpanel/bridge 0.10.30 → 0.10.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/bridge",
-  "version": "0.10.30",
+  "version": "0.10.32",
   "type": "module",
   "description": "Local bridge that exposes the AI coding agents installed on your machine \u2014 Claude Code (CLI), Codex (CLI), and Antigravity CLI (formerly Gemini CLI, which remains available for business/enterprise) \u2014 to the ChatPanel Chrome extension over a localhost SSE endpoint. Bring your own agent.",
   "keywords": [

package/scripts/sync-events.mjs

@@ -21,7 +21,7 @@ const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 // Deliberately short. `skill-manifest.js` imports only `scopes.js`, which is why that
 // vocabulary was split out of `capability.js` — vendoring the capability machinery and
 // the event schema to reach a five-element array would defeat the point.
-const FILES = ['scopes.js', 'skill-manifest.js'];
+const FILES = ['scopes.js', 'skill-manifest.js', 'skill-scan.js'];
 
 function pkgDir() {
   return [

package/src/events/skill-scan.js

@@ -0,0 +1,218 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/skill-scan.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// skill-scan.js — is this skill safe to admit?
+//
+// A SKILL.md is a prompt that will run with page tools, MCP servers and history attached.
+// Once skills can arrive from a hub, a repo or a shared folder, that makes it an injection
+// payload with a distribution channel — the reason every serious agent harness quarantines
+// what it installs. This is the gate F6 puts in front of admission.
+//
+// THE PRECISION PROBLEM IS THE WHOLE DESIGN. A scanner that flags legitimate skills is
+// worse than none: people learn to click past it, and then it protects nothing. Real
+// skills are full of shell examples, curl commands and API docs. So:
+//
+//   • `dangerous` requires high-precision evidence — an instruction override aimed at the
+//     model, or a CREDENTIAL PATH combined with an OUTBOUND SINK in the same breath.
+//     Neither half alone is enough: `curl https://api.example.com` is documentation and
+//     `~/.aws/credentials` is a sentence about configuration.
+//   • `suspicious` is for things worth a human glance that are not proof of anything.
+//   • everything else is `clean`, and the common case must be clean.
+//
+// It is a heuristic gate, not a proof. It stops the obvious and the careless; it is not a
+// claim that an admitted skill is safe, which is why provenance stays visible at use time
+// and why scripts stay behind a separate confirmation.
+//
+// Pure and clock-free: the caller stamps the time, so the same input always produces the
+// same finding list and a verdict can be cached by content hash.
+
+export class SkillScanError extends Error {
+  constructor(code, message) { super(message); this.name = 'SkillScanError'; this.code = code; }
+}
+
+/** Bump when a rule changes: a cached verdict from an older scanner must not be trusted. */
+export const SCANNER_VERSION = 1;
+
+export const SCAN_VERDICTS = Object.freeze(['clean', 'suspicious', 'dangerous']);
+
+const RANK = { clean: 0, suspicious: 1, dangerous: 2 };
+
+// Characters that carry no visible meaning and exist in a prompt for one reason: to hide
+// text from the person reading it while the model still sees it. Zero-width joiners,
+// bidirectional overrides, and the Unicode tag block used for "invisible" instructions.
+// eslint-disable-next-line no-misleading-character-class
+const HIDDEN = /[​-‏‪-‮⁠-⁤⁦-⁩\u{e0000}-\u{e007f}]/u;
+
+// Aimed at the MODEL rather than describing anything. Deliberately narrow: "ignore the
+// previous section" is ordinary prose, "ignore all previous instructions" is not.
+const OVERRIDE = [
+  /\bignore\s+(?:all\s+|any\s+)?(?:previous|prior|earlier|above)\s+(?:instructions?|prompts?|rules?|directions?)\b/i,
+  /\bdisregard\s+(?:all\s+|any\s+)?(?:previous|prior|the)\s+(?:instructions?|system\s+prompt|rules?)\b/i,
+  /\b(?:forget|override)\s+(?:everything|all)\s+(?:you|above|previously)\b/i,
+  /\byou\s+are\s+no\s+longer\s+(?:bound|restricted|required)\b/i,
+  /<\/?(?:system|assistant)\b[^>]*>/i,
+  /\bnew\s+system\s+prompt\s*:/i,
+];
+
+// Telling the model to keep something from the person it is working for. Real injection
+// signature — and also, sometimes, ordinary editorial guidance, which is why it is
+// SUSPICIOUS rather than dangerous.
+//
+// Codex's own `plugin-creator` skill is the case that settled the severity: it says "Do
+// not tell the user to run `codex plugin marketplace add`", which is advice about what to
+// recommend, not concealment. A first-party skill quarantined by a rule that cannot tell
+// those apart would teach people to click past the gate — so the phrasing is narrowed
+// (`to <verb>` is excluded) AND the severity is honest about what the match proves.
+const CONCEALMENT = [
+  /\b(?:do\s+not|don't|never)\s+(?:tell|inform)\s+the\s+user\b(?!\s+to\s)/i,
+  /\b(?:do\s+not|don't|never)\s+(?:mention|reveal|disclose)\s+(?:this|that|it|any(?:thing)?)?\s*to\s+the\s+user\b/i,
+  /\bwithout\s+(?:telling|informing|notifying)\s+the\s+user\b/i,
+  /\bhide\s+(?:this|that|it)\s+from\s+the\s+user\b/i,
+];
+
+// Things that identify a secret. A path or a well-known variable name — not the word
+// "token", which appears in every API document ever written.
+const CREDENTIAL = [
+  /~\/\.ssh\/|\bid_rsa\b|\bid_ed25519\b/i,
+  /~\/\.aws\/credentials|\bAWS_SECRET_ACCESS_KEY\b/i,
+  /\.env\b(?!\w)|\bprintenv\b|\benv\s*\|/i,
+  /~\/\.netrc|\.git-credentials|\bkeychain\s+dump\b/i,
+  /\bGITHUB_TOKEN\b|\bNPM_TOKEN\b|\bOPENAI_API_KEY\b|\bANTHROPIC_API_KEY\b/,
+  /~\/\.config\/(?:gh|gcloud)\/|\bgcloud\s+auth\s+print-access-token\b/i,
+];
+
+// Something that sends data OFF the machine. An outbound body, not a fetch.
+const SINK = [
+  /\bcurl\b[^\n|]*(?:-d|--data|--data-binary|-F|--form|-T|--upload-file)\b/i,
+  /\bwget\b[^\n|]*--post-(?:data|file)\b/i,
+  /\b(?:nc|netcat|ncat)\b\s+[\w.-]+\s+\d+/i,
+  /\bfetch\s*\([^)]*method\s*:\s*['"]POST/i,
+  /\brequests\.post\s*\(/i,
+  /\|\s*(?:curl|nc|netcat)\b/i,
+  /\bscp\b\s+\S+\s+\S+@/i,
+];
+
+// Irreversible, and never something a skill document needs to demonstrate literally.
+const DESTRUCTIVE = [
+  { re: /\brm\s+-[a-z]*[rR][a-z]*f[a-z]*\s+(?:--no-preserve-root\s+)?(?:\/|~|\$HOME)(?:\/\s|\/?[`'"\s]|$)/, why: 'recursive delete of a root or home directory' },
+  { re: /\bmkfs(?:\.\w+)?\b/, why: 'filesystem format' },
+  { re: /\bdd\s+[^\n]*\bof=\/dev\/(?:sd|nvme|disk)/, why: 'raw write to a block device' },
+  { re: /:\(\)\s*\{\s*:\|:&\s*\}\s*;\s*:/, why: 'fork bomb' },
+  { re: /\bchmod\s+-R\s+777\s+\//, why: 'world-writable root' },
+  { re: /\bhistory\s+-c\b|\bshred\b\s+[^\n]*\.(?:log|history)/, why: 'covering tracks' },
+];
+
+const SUSPECT = [
+  { re: /\b(?:eval|exec)\s*\(\s*(?:atob|base64|Buffer\.from)/i, why: 'executes decoded content' },
+  { re: /\bbase64\s+-d\b[^\n]*\|\s*(?:sh|bash|zsh|python)/i, why: 'pipes decoded content to a shell' },
+  { re: /\bcurl\b[^\n]*\|\s*(?:sudo\s+)?(?:sh|bash|zsh)\b/i, why: 'pipes a download straight into a shell' },
+  { re: /[A-Za-z0-9+/]{280,}={0,2}/, why: 'a large opaque base64 blob' },
+  { re: /\bhttp:\/\/(?!localhost|127\.0\.0\.1|\[::1\])[\w.-]+/i, why: 'sends or fetches over plain HTTP' },
+  { re: /\bsudo\s+(?:-S\s+)?[^\n]*<<</i, why: 'feeds a password to sudo' },
+];
+
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+const excerpt = (text, index, len = 90) => text.slice(Math.max(0, index - 10), index + len).replace(/\s+/g, ' ').trim();
+
+function find(text, re) {
+  const m = re.exec(text);
+  return m ? { index: m.index, match: m[0] } : null;
+}
+
+/**
+ * Scan one skill.
+ *
+ * @param name    for the finding messages
+ * @param prompt  the SKILL.md body — the thing that becomes a prompt
+ * @param files   declared package paths, e.g. ['references/a.md', 'scripts/run.py']
+ * @param extra   additional text to scan (a reference document's contents, when the caller
+ *                has fetched them). Scanned under the same rules: a skill that points at a
+ *                clean-looking file which itself carries the payload is the obvious dodge.
+ *
+ * -> { verdict, findings: [{ rule, severity, line, excerpt, why }], scanner }
+ */
+export function scanSkill({ name = '', prompt = '', files = [], extra = '' } = {}) {
+  const text = [String(prompt || ''), String(extra || '')].filter(Boolean).join('\n\n');
+  const findings = [];
+  const add = (rule, severity, hit, why) => {
+    findings.push({
+      rule,
+      severity,
+      why,
+      line: hit ? lineOf(text, hit.index) : 0,
+      excerpt: hit ? excerpt(text, hit.index) : '',
+    });
+  };
+
+  if (HIDDEN.test(text)) {
+    // No legitimate reason for a procedure document to contain characters the reader
+    // cannot see but the model can.
+    add('hidden-text', 'dangerous', find(text, HIDDEN), 'contains characters that are invisible to a reader but not to the model');
+  }
+
+  for (const re of OVERRIDE) {
+    const hit = find(text, re);
+    if (hit) { add('instruction-override', 'dangerous', hit, 'tries to override the instructions it is running under'); break; }
+  }
+
+  for (const re of CONCEALMENT) {
+    const hit = find(text, re);
+    if (hit) { add('concealment', 'suspicious', hit, 'asks the model to keep something from the user'); break; }
+  }
+
+  // The combination is the evidence. Either half alone is ordinary documentation.
+  const cred = CREDENTIAL.map((re) => find(text, re)).find(Boolean);
+  const sink = SINK.map((re) => find(text, re)).find(Boolean);
+  if (cred && sink) {
+    add('credential-exfiltration', 'dangerous', cred, `names a credential (${cred.match.trim().slice(0, 40)}) alongside a command that sends data off the machine`);
+  } else if (cred) {
+    add('credential-mention', 'suspicious', cred, 'refers to a credential file or secret variable');
+  } else if (sink) {
+    add('outbound-data', 'suspicious', sink, 'sends data to a remote host');
+  }
+
+  for (const { re, why } of DESTRUCTIVE) {
+    const hit = find(text, re);
+    if (hit) add('destructive-command', 'dangerous', hit, why);
+  }
+
+  for (const { re, why } of SUSPECT) {
+    const hit = find(text, re);
+    if (hit) add('suspicious-pattern', 'suspicious', hit, why);
+  }
+
+  // Scripts are not scanned as prose — they are code, and this is not a code analyser.
+  // Their presence is reported so the reviewer knows execution is on the table at all.
+  const scripts = (Array.isArray(files) ? files : []).filter((f) => String(f).startsWith('scripts/'));
+  if (scripts.length) {
+    findings.push({
+      rule: 'ships-executable',
+      severity: 'suspicious',
+      why: `ships ${scripts.length} executable file${scripts.length === 1 ? '' : 's'} (${scripts.join(', ')}) — these run on your machine, not in the browser`,
+      line: 0,
+      excerpt: '',
+    });
+  }
+
+  const verdict = findings.reduce((worst, f) => (RANK[f.severity] > RANK[worst] ? f.severity : worst), 'clean');
+  return { verdict, findings, scanner: SCANNER_VERSION, name: String(name || '') };
+}
+
+/** Is this verdict allowed to enter the index at all? */
+export function admits(verdict) {
+  return verdict !== 'dangerous';
+}
+
+/** A one-line reason, for a card or a refusal. */
+export function scanSummary(scan) {
+  if (!scan || scan.verdict === 'clean') return '';
+  const worst = (scan.findings || []).filter((f) => f.severity === scan.verdict);
+  const first = worst[0];
+  const more = worst.length > 1 ? ` (+${worst.length - 1} more)` : '';
+  return first ? `${first.why}${more}` : scan.verdict;
+}

package/src/mcp-capabilities.js

@@ -0,0 +1,140 @@
+// mcp-capabilities.js — ChatPanel's own capabilities, exposed as MCP tools.
+//
+// The /mcp endpoint used to relay ONLY the page tools of an active browser chat: nothing
+// to offer unless ChatPanel was open and driving. That makes ChatPanel a thing you drive,
+// never a thing another agent can draw on. This is the other direction — a Codex or a
+// Claude Code that adds the ChatPanel MCP server once gets ChatPanel's bridge-native
+// capabilities as ordinary tools, whether or not a browser is open.
+//
+// A REGISTRY, so a new capability becomes an MCP tool by being registered — not by editing
+// the MCP handler. That is the whole point of the ask "future capabilities should be
+// available automatically": the handler enumerates this list, it does not hardcode a set.
+//
+// WHAT BELONGS HERE: capabilities the bridge can serve on its own — skills (on disk),
+// redaction (the vendored pii engine), local MCP proxying. Notes, meetings and chat history
+// live in the browser's encrypted on-device store; the bridge cannot read them, so they are
+// NOT here — they stay behind the active-session relay (or a future shared store), and
+// exposing on-device history to an external CLI is a privacy decision to make deliberately,
+// not a tool to switch on by default.
+
+import { skillIndex, listRecords, readRecord, readPackageFile } from './skills.js';
+import { sanitizeUnicode, hasHiddenChars } from './sanitize.js';
+
+const MAX_REF = 24_000;
+
+/**
+ * The always-on capability tools. Each: { name, description, schema, run(args) -> content }.
+ * `run` returns MCP content parts. Kept small and pure-ish; the store calls are the only IO.
+ */
+export function capabilityTools() {
+  return [
+    {
+      name: 'chatpanel_skill_list',
+      description:
+        'List the skills installed on this machine that ChatPanel can see — across every '
+        + 'agent harness (Claude Code, Codex, Copilot, Gemini, Hermes, ~/.agents) and any '
+        + 'configured folder. Returns each skill\'s name and one-line description. Call this '
+        + 'first, then chatpanel_skill_open to load the instructions of the one that fits.',
+      schema: { type: 'object', properties: {} },
+      async run() {
+        const { index } = await skillIndex();
+        const rows = listRecords(index).map((s) => ({
+          name: s.command || s.id,
+          title: s.name,
+          description: s.description || '',
+          from: s.origin?.source || 'local',
+          references: (s.files?.references || []).length || undefined,
+        }));
+        return text(JSON.stringify({ skills: rows }, null, 2));
+      },
+    },
+    {
+      name: 'chatpanel_skill_open',
+      description:
+        'Load one skill\'s full instructions by name (from chatpanel_skill_list). Follow what '
+        + 'it returns. If the instructions point at reference files, read one with '
+        + 'chatpanel_skill_read.',
+      schema: {
+        type: 'object',
+        properties: { name: { type: 'string', description: 'The skill name from chatpanel_skill_list.' } },
+        required: ['name'],
+      },
+      async run(args) {
+        const { index } = await skillIndex();
+        const skill = readRecord(index, String(args?.name || '').trim());
+        if (!skill) return text(`No such skill "${args?.name}". Use chatpanel_skill_list to see what is available.`, true);
+        return text(skill.prompt || '(this skill has no extra instructions — just apply it.)');
+      },
+    },
+    {
+      name: 'chatpanel_skill_read',
+      description:
+        'Read one reference file a skill\'s instructions point at (any path inside the skill\'s '
+        + 'own folder). Use only when the task needs it.',
+      schema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'The skill name.' },
+          path: { type: 'string', description: 'The reference path as written in the instructions, e.g. references/auth.md.' },
+        },
+        required: ['name', 'path'],
+      },
+      async run(args) {
+        const { index } = await skillIndex();
+        const out = await readPackageFile(index, String(args?.name || '').trim(), String(args?.path || '').trim());
+        if (out.error) return text(`Could not read it: ${out.error}`, true);
+        const body = out.text.length > MAX_REF ? `${out.text.slice(0, MAX_REF)}\n\n…[truncated]` : out.text;
+        return text(body);
+      },
+    },
+    {
+      // Bridge-native security hygiene: strip the invisible and look-alike characters used to
+      // smuggle instructions past a human reader — a real risk for a CLI processing pasted or
+      // fetched text. This is the unicode layer, honestly scoped: it is NOT full PII redaction
+      // (names, emails), which lives in the gateway with the complete engine. Naming it
+      // precisely matters more than sounding capable.
+      name: 'chatpanel_sanitize_text',
+      description:
+        'Remove hidden and look-alike Unicode characters from text (zero-width joiners, '
+        + 'bidirectional overrides, the tag block, homoglyphs) — the tricks used to hide '
+        + 'instructions from a human while a model still sees them. Returns the cleaned text and '
+        + 'what was removed. Use before trusting text pasted or fetched from an untrusted source. '
+        + 'This is not full PII redaction (names, emails) — that lives in the ChatPanel gateway.',
+      schema: {
+        type: 'object',
+        properties: { text: { type: 'string', description: 'The text to sanitize.' } },
+        required: ['text'],
+      },
+      async run(args) {
+        const input = String(args?.text ?? '');
+        const { clean, removed, findings } = sanitizeUnicode(input);
+        return text(JSON.stringify({
+          clean,
+          hadHiddenCharacters: hasHiddenChars(input),
+          removed: removed || 0,
+          findings: findings || {}, // per-category counts, e.g. { bidi: 1, zeroWidth: 2 }
+        }, null, 2));
+      },
+    },
+  ];
+}
+
+function text(s, isError = false) {
+  return { content: [{ type: 'text', text: String(s) }], ...(isError ? { isError: true } : {}) };
+}
+
+/** MCP tools/list shape for the capability tools. */
+export function capabilityToolSpecs() {
+  return capabilityTools().map((t) => ({ name: t.name, description: t.description, inputSchema: t.schema }));
+}
+
+/** Run one capability tool by name, or null if it is not one of ours. */
+export async function runCapabilityTool(name, args) {
+  const tool = capabilityTools().find((t) => t.name === name);
+  if (!tool) return null;
+  try {
+    return await tool.run(args || {});
+  } catch (e) {
+    return text(`error: ${e?.message || e}`, true);
+  }
+}

package/src/server.js

@@ -37,7 +37,8 @@ import { pi, opencode, kiro, copilot, deepseek } from './engines/cli-agents.js';
 import { connectorsFor } from './connectors.js';
 import * as custom from './engines/custom.js';
 import { installService, uninstallService, serviceStatus, restartService } from './service.js';
-import { skillIndex, listRecords, readRecord, readPackageFile, skillsHealth } from './skills.js';
+import { skillIndex, listRecords, readRecord, readPackageFile, skillsHealth, quarantinedSkills } from './skills.js';
+import { capabilityToolSpecs, runCapabilityTool } from './mcp-capabilities.js';
 import { DEFAULT_WORKSPACE, isDefaultWorkdir, resolveWorkdir, writeScopeNote } from './workdir.js';
 import { AGENT_CLIS, enrichPath, enrichAgentEnv, findAgentBin, resolveCommand } from './env.js';
 import { stripHidden } from './sanitize.js';
@@ -66,7 +67,7 @@ import {
 // Hardcoded (not read from package.json) so it survives Bun's single-file
 // --compile, where package.json isn't on a readable FS. CI fails the publish if
 // this drifts from package.json, so the two can't silently diverge.
-const VERSION = '0.10.30';
+const VERSION = '0.10.32';
 const HOST = process.env.CHATPANEL_BRIDGE_HOST || '127.0.0.1';
 const PORT = Number(process.env.CHATPANEL_BRIDGE_PORT) || 4319;
 
@@ -386,20 +387,24 @@ async function handleHealth(res) {
 // The three routes are the progressive-disclosure ladder, so a client pays for a
 // skill's body only when it picks one, and for a reference file only when it needs it.
 // --------------------------------------------------------------------------
-async function handleSkillsList(res) {
-  const { index, problems } = await skillIndex();
+async function handleSkillsList(res, extraDirs) {
+  const { index, problems } = await skillIndex({ extraDirs });
   json(res, 200, { ok: true, skills: listRecords(index), problems });
 }
 
-async function handleSkillRead(res, name) {
-  const { index } = await skillIndex();
+async function handleSkillsQuarantined(res, extraDirs) {
+  json(res, 200, { ok: true, quarantined: await quarantinedSkills(extraDirs) });
+}
+
+async function handleSkillRead(res, name, extraDirs) {
+  const { index } = await skillIndex({ extraDirs });
   const skill = readRecord(index, name);
   if (!skill) return json(res, 404, { ok: false, error: 'unknown skill' });
   json(res, 200, { ok: true, skill });
 }
 
-async function handleSkillFile(res, name, relPath) {
-  const { index } = await skillIndex();
+async function handleSkillFile(res, name, relPath, extraDirs) {
+  const { index } = await skillIndex({ extraDirs });
   const out = await readPackageFile(index, name, relPath);
   // One shape for every refusal: a caller learns that it may not have the file, not
   // whether the path exists, which is the difference between an error and an oracle.
@@ -740,22 +745,27 @@ async function handleMcp(req, res, sessionId) {
       serverInfo: { name: 'chatpanel-browser', version: VERSION },
     });
   }
-  // No active chat → advertise zero tools rather than erroring, so a CLI with a
-  // standing /mcp config (run outside ChatPanel) starts cleanly instead of failing.
-  if (!session) {
-    if (msg.method === 'tools/list') return reply({ tools: [] });
-    return fail(-32001, 'No active ChatPanel session — open a chat with “Act on page” on.');
-  }
+  // ChatPanel's own bridge-native capabilities (skills today; redaction and more later) are
+  // ALWAYS advertised — a CLI that added this server once gets them whether or not a browser
+  // chat is open. The active session's page tools are added ON TOP when a chat is driving.
+  const capTools = capabilityToolSpecs();
+
   if (msg.method === 'tools/list') {
-    return reply({
-      tools: session.specs.map((s) => ({
+    const pageTools = session
+      ? session.specs.map((s) => ({
         name: s.name,
         description: s.description,
         inputSchema: s.parameters || { type: 'object', properties: {} },
-      })),
-    });
+      }))
+      : [];
+    return reply({ tools: [...capTools, ...pageTools] });
   }
   if (msg.method === 'tools/call') {
+    // A capability tool runs in the bridge and needs no browser; a page tool relays to the
+    // active chat. Capability tools win a name clash — they are ours and namespaced.
+    const cap = await runCapabilityTool(msg.params?.name, msg.params?.arguments || {});
+    if (cap) return reply(cap);
+    if (!session) return fail(-32001, 'That tool needs an active ChatPanel chat with “Act on page” on. ChatPanel\'s own tools (chatpanel_*) work without one.');
     try {
       return reply(await relayToolCall(session, msg.params?.name, msg.params?.arguments || {}));
     } catch (e) {
@@ -1061,15 +1071,21 @@ const server = createServer(async (req, res) => {
   if (blocked) return json(res, 403, { error: blocked });
   try {
     if (req.method === 'GET' && url.pathname === '/health') return handleHealth(res);
-    if (req.method === 'GET' && url.pathname === '/skills') return handleSkillsList(res);
+    // Custom skill folders the user configured in the extension, passed per request. They
+    // are the user's own absolute paths on their own machine; the bridge validates and
+    // scans them, and the same traversal/symlink guards apply to any file read from them.
+    const extraDirs = url.searchParams.getAll('dir');
+    if (req.method === 'GET' && url.pathname === '/skills') return handleSkillsList(res, extraDirs);
+    if (req.method === 'GET' && url.pathname === '/skills-quarantined') return handleSkillsQuarantined(res, extraDirs);
     if (req.method === 'GET' && url.pathname.startsWith('/skills/')) {
       const rest = url.pathname.slice('/skills/'.length);
       const cut = rest.indexOf('/file/');
-      if (cut === -1) return handleSkillRead(res, decodeURIComponent(rest));
+      if (cut === -1) return handleSkillRead(res, decodeURIComponent(rest), extraDirs);
       return handleSkillFile(
         res,
         decodeURIComponent(rest.slice(0, cut)),
         decodeURIComponent(rest.slice(cut + '/file/'.length)),
+        extraDirs,
       );
     }
     if (req.method === 'GET' && url.pathname === '/v1/models') return handleCompatibleModels(res);

package/src/skills.js

@@ -36,13 +36,19 @@
 import { readFile as fsReadFile, readdir, stat, realpath } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import os from 'node:os';
-import { delimiter, join, resolve, sep } from 'node:path';
+import { delimiter, isAbsolute, join, resolve, sep } from 'node:path';
 import { isSafeSkillPath, normalizeSkill, SKILL_FILE_KINDS } from './events/skill-manifest.js';
+import { scanSkill, admits } from './events/skill-scan.js';
 
 const MAX_SKILL_MD = 512 * 1024;   // a procedure document, not a corpus
 const MAX_ASSET = 4 * 1024 * 1024; // a reference doc or a template; images live elsewhere
 const MAX_SKILLS = 500;            // a scan is bounded work, not "whatever is on disk"
-const MAX_DEPTH = 2;               // <root>/<name>/ and <root>/<category>/<name>/
+const MAX_DEPTH = 3;               // <root>/<name>/, <root>/<category>/<name>/, and one
+                                   // namespace above that (Codex: .system/<name>/)
+
+// Never a skill and never worth walking: version control and package metadata. Everything
+// else hidden IS walked — see the namespace note in scanSkills.
+const SKIP_DIRS = new Set(['.git', '.svn', '.hg', '.cache', '.DS_Store', 'node_modules']);
 
 /**
  * The agent CLIs that keep skills in a well-known directory, and what to call each one.
@@ -80,15 +86,29 @@ export const AGENT_SKILL_DIRS = Object.freeze([
  * Only the first is written. The rest belong to whatever else the user runs, and a tool
  * that edits another tool's configuration directory is a tool people uninstall.
  */
-export function skillRoots(env = process.env, home = os.homedir()) {
+// User-configured folders come from two places: CHATPANEL_SKILL_DIRS (env, for an operator)
+// and the extension's own setting, passed per request as `extraDirs`. Both are the user's
+// OWN paths on their OWN machine reached over an authed loopback call — so they are allowed,
+// but only if they are ABSOLUTE. A relative or empty entry is dropped rather than resolved
+// against the bridge's cwd, which would scan somewhere the user never named.
+function cleanDirs(list) {
+  return (Array.isArray(list) ? list : [])
+    .map((d) => String(d || '').trim())
+    .filter(Boolean)
+    .filter((d) => isAbsolute(d))
+    .slice(0, 16); // a bound, not a limit anyone will hit
+}
+
+export function skillRoots(env = process.env, home = os.homedir(), extraDirs = []) {
   // Split on the PLATFORM's list separator, not a fixed set. Splitting on ':' everywhere
   // cut "C:\\Users\\me\\skills" into "C" and "\\Users\\me\\skills" on Windows, which is the
   // one platform where a drive letter makes that character part of an ordinary path.
-  const extra = String(env.CHATPANEL_SKILL_DIRS || '')
+  const fromEnv = String(env.CHATPANEL_SKILL_DIRS || '')
     .split(/\r?\n/)
     .flatMap((line) => line.split(delimiter))
     .map((s) => s.trim())
     .filter(Boolean);
+  const extra = [...new Set([...fromEnv, ...cleanDirs(extraDirs)])];
   return [
     ...AGENT_SKILL_DIRS.map((d) => ({
       dir: join(home, ...d.segments),
@@ -96,7 +116,7 @@ export function skillRoots(env = process.env, home = os.homedir()) {
       label: d.label,
       writable: !!d.writable,
     })),
-    ...extra.map((dir) => ({ dir: resolve(dir), source: 'external', label: 'Custom', writable: false })),
+    ...extra.map((dir) => ({ dir: resolve(dir), source: 'external', label: 'Custom folder', writable: false })),
   ];
 }
 
@@ -223,31 +243,49 @@ async function loadSkill(dir, relPath, source) {
   const dirName = relPath.split('/').pop();
   const files = await packageFiles(dir);
   const skill = skillRecord({ meta, body, dirName, relPath, source, files, hash });
-  return { skill, dir };
+  // Scanned before it can enter the index — even a local skill, because a folder synced
+  // from elsewhere or pulled by another tool is not something the user wrote. The verdict
+  // rides on the origin so a client can show it; the caller quarantines a dangerous one.
+  const scan = scanSkill({ name: skill.name, prompt: skill.prompt, files: files || [] });
+  skill.origin = { ...skill.origin, scanned: { verdict: scan.verdict, scanner: scan.scanner, findings: scan.findings.length } };
+  return { skill, dir, scan };
 }
 
 /**
  * Scan every root. Returns an INDEX keyed by id — and that index is the only thing a
  * later read may resolve a requested name against.
  */
-export async function scanSkills({ roots = skillRoots(), platform = process.platform } = {}) {
+export async function scanSkills({ roots, extraDirs = [], platform = process.platform } = {}) {
+  roots = roots || skillRoots(process.env, os.homedir(), extraDirs);
   const index = new Map();
   const problems = [];
+  const quarantined = [];
   for (const { dir: root, source } of roots) {
     const walk = async (dir, rel, depth) => {
       if (index.size >= MAX_SKILLS || depth > MAX_DEPTH) return;
       for (const entry of await listDir(dir)) {
         if (index.size >= MAX_SKILLS) return;
-        if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+        if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
         const childRel = rel ? `${rel}/${entry.name}` : entry.name;
         const child = join(dir, entry.name);
-        const loaded = await loadSkill(child, childRel, source).catch((e) => {
-          problems.push({ path: childRel, reason: String(e?.message || e) });
-          return null;
-        });
+        // A hidden directory is a NAMESPACE, not a skill. Codex ships its built-ins under
+        // `~/.codex/skills/.system/<name>/SKILL.md`, so skipping every dot-directory —
+        // which was aimed at `.git` — hid six real skills. Walk through it, but never let
+        // it become a skill id of its own.
+        const loaded = entry.name.startsWith('.')
+          ? null
+          : await loadSkill(child, childRel, source).catch((e) => {
+            problems.push({ path: childRel, reason: String(e?.message || e) });
+            return null;
+          });
         if (loaded) {
-          // First root wins: ChatPanel's own directory is authoritative over a shared one.
-          if (!index.has(loaded.skill.id) && platformOk(loaded.skill, platform)) {
+          // A dangerous skill is kept on disk (the user may want to inspect or remove it)
+          // but never enters the index — so it cannot be listed, read, offered as a slash
+          // command, or handed to a model. Recorded so a client can say WHY it is missing.
+          if (!admits(loaded.scan?.verdict)) {
+            quarantined.push({ id: loaded.skill.id, path: childRel, verdict: loaded.scan.verdict, findings: loaded.scan.findings });
+          } else if (!index.has(loaded.skill.id) && platformOk(loaded.skill, platform)) {
+            // First root wins: ChatPanel's own directory is authoritative over a shared one.
             index.set(loaded.skill.id, { ...loaded, root, source });
           }
         } else {
@@ -257,7 +295,7 @@ export async function scanSkills({ roots = skillRoots(), platform = process.plat
     };
     await walk(root, '', 1);
   }
-  return { index, problems };
+  return { index, problems, quarantined };
 }
 
 /** Level 0 — what exists, cheaply. No bodies. */
@@ -285,10 +323,16 @@ export async function readPackageFile(index, name, relPath) {
   const hit = index.get(String(name || ''));
   if (!hit) return { error: 'unknown skill' };
   if (!isSafeSkillPath(relPath)) return { error: 'unsafe path' };
-  // '/' by wire contract — the HTTP path is URL-shaped, and isSafeSkillPath already
-  // refuses backslashes, so a Windows-style separator never reaches here.
-  const kind = String(relPath).split('/')[0];
-  if (!SKILL_FILE_KINDS.includes(kind)) return { error: 'unsafe path' };
+  // A skill's docs live wherever its author put them — a flat references/ for simple ones,
+  // a deep tree (foundry-agent/deploy/deploy.md, rbac/, quota/…) for rich ones. The SKILL.md
+  // IS the map, so the readable set is "any file inside this skill's own folder", enforced
+  // below by realpath containment — not a fixed list of top-level directory names, which
+  // silently refused every nested reference the skill's own instructions pointed at.
+  //
+  // The one exception is scripts/: tier-3 executable code is run behind a confirmation, never
+  // handed to a model as text. '/' by wire contract — isSafeSkillPath already refuses
+  // backslashes, so a Windows separator never reaches here.
+  if (String(relPath).split('/')[0] === 'scripts') return { error: 'scripts are not readable as text' };
 
   const target = resolve(hit.dir, relPath);
   let real;
@@ -318,26 +362,38 @@ export async function readPackageFile(index, name, relPath) {
 const CACHE_MS = 5000;
 let cached = null;
 
-export async function skillIndex({ force = false, now = Date.now } = {}) {
+export async function skillIndex({ force = false, now = Date.now, extraDirs = [] } = {}) {
   const t = now();
-  if (!force && cached && t - cached.at < CACHE_MS) return cached.value;
-  const value = await scanSkills();
-  cached = { at: t, value };
+  // The cache key includes the custom folders — a scan with extra dirs must not serve, or be
+  // served by, one without them.
+  const key = cleanDirs(extraDirs).map((d) => resolve(d)).sort().join('|');
+  if (!force && cached && cached.key === key && t - cached.at < CACHE_MS) return cached.value;
+  const value = await scanSkills({ extraDirs });
+  cached = { at: t, key, value };
   return value;
 }
 
 export function clearSkillCache() { cached = null; }
 
 /** The `/health` summary — counts and roots, never contents. */
-export async function skillsHealth() {
-  const { index, problems } = await skillIndex();
+export async function skillsHealth(extraDirs = []) {
+  const { index, problems, quarantined } = await skillIndex({ extraDirs });
   const used = new Set([...index.values()].map((v) => v.root));
   return {
     count: index.size,
     // Only roots that actually contributed. A list of every path we looked in would be
     // mostly absent directories, and would say nothing about what the user has.
-    roots: skillRoots().filter((r) => used.has(r.dir)).map((r) => r.dir),
+    roots: skillRoots(process.env, os.homedir(), extraDirs).filter((r) => used.has(r.dir)).map((r) => r.dir),
     sources: [...new Set([...index.values()].map((v) => v.source))].sort(),
     ...(problems.length ? { problems: problems.length } : {}),
+    // A count, not the contents. That there is a blocked skill is worth surfacing; the
+    // findings are read on demand, not broadcast on every health poll.
+    ...(quarantined?.length ? { quarantined: quarantined.length } : {}),
   };
 }
+
+/** The blocked skills, with their findings — for a client that wants to show them. */
+export async function quarantinedSkills(extraDirs = []) {
+  const { quarantined } = await skillIndex({ extraDirs });
+  return quarantined || [];
+}