@guardion/guardion 0.2.0 → 0.4.0

package/dist/connectors/claude-code/hooks/enforce.cjs

@@ -0,0 +1,58 @@
+'use strict';
+/**
+ * P2 enforcement mapping (pure, testable) — Claude-Code-native equivalent of
+ * AGT's MCP gateway dual-stage pipeline. PreToolUse scans tool INPUT, PostToolUse
+ * scans tool OUTPUT. The decision FOLLOWS THE POLICY ACTION: the Guard server
+ * returns `deny` only when policy.action=block, so:
+ *   res.deny    → DENY  (PreToolUse: permissionDecision deny / PostToolUse: block)
+ *   res.flagged → FLAG  (warn, non-blocking additionalContext) — action=flag, or
+ *                 a held step_up/defer
+ * Default fail-OPEN; fail-closed only when explicitly enabled.
+ */
+
+/** Build the tool message sent to /v1/guard from a Claude Code hook payload. */
+function toolMessage(event, payload) {
+  const toolName = payload.tool_name || payload.toolName || '';
+  if (event === 'PostToolUse') {
+    const resp = payload.tool_response != null ? payload.tool_response
+               : (payload.tool_output != null ? payload.tool_output : '');
+    // Canonical Guard role is `tool_response` (NOT `tool_output`, which is a
+    // Target name) — must match MessagesRole in guard/guard/core/schemas.py.
+    return { role: 'tool_response', name: toolName,
+             content: typeof resp === 'string' ? resp : JSON.stringify(resp || '') };
+  }
+  const input = payload.tool_input != null ? payload.tool_input : (payload.toolInput || {});
+  const inputText = typeof input === 'string' ? input : JSON.stringify(input || {});
+  return { role: 'tool_input', name: toolName, content: `${toolName} ${inputText}`.trim() };
+}
+
+function guardReason(res) {
+  try {
+    const b = res && Array.isArray(res.breakdown) ? res.breakdown[0] : null;
+    const label = b && (b.top_label || b.label);
+    return label ? `Guardion governance: ${label}` : 'Guardion governance policy';
+  } catch { return 'Guardion governance policy'; }
+}
+
+/** Map a Guard verdict → Claude Code hook decision JSON, or null to allow. */
+function enforceDecision(event, res, failClosed) {
+  if (!res) {   // Guard unreachable / timeout
+    if (!failClosed) return null;            // fail-open (default): allow
+    return event === 'PreToolUse'
+      ? { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny',
+          permissionDecisionReason: 'Guardion governance unavailable (fail-closed)' } }
+      : { decision: 'block', reason: 'Guardion governance unavailable (fail-closed)' };
+  }
+  const reason = guardReason(res);
+  if (res.deny) {                            // policy.action=block → DENY
+    return event === 'PreToolUse'
+      ? { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } }
+      : { decision: 'block', reason };
+  }
+  if (res.flagged) {                         // policy.action=flag → FLAG (warn, non-blocking)
+    return { hookSpecificOutput: { hookEventName: event, additionalContext: `[guardion] flagged — ${reason}` } };
+  }
+  return null;                               // allow
+}
+
+module.exports = { toolMessage, guardReason, enforceDecision };

package/dist/connectors/claude-code/hooks/guardion-hook.cjs

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+/**
+ * Guardion Claude Code hook — tier-aware event forwarder.
+ *
+ * Tiers:
+ *   hooks — fire-and-forget POST to Guard API, no LLM proxy involvement
+ *   full  — same + on SessionStart injects x-guardion-trace-id into
+ *             ANTHROPIC_CUSTOM_HEADERS so every LLM call through the
+ *             Guardion gateway is correlated to this session
+ *
+ * Config (~/.guardion/config.json, written by `npx guardion init`):
+ *   tier, api_url, policy, application, gateway.*, hooks.events, hooks.timeout_ms
+ *
+ * Token resolution (first match wins):
+ *   GUARDION_TOKEN env  →  macOS Keychain  →  /etc/guardion/token  →  ~/.guardion/token
+ *
+ * Always exits 0 — never blocks Claude Code.
+ */
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const http  = require('http');
+const https = require('https');
+const { execFileSync } = require('child_process');
+
+// ── Paths ────────────────────────────────────────────────────────────────────
+
+const HOME_DIR         = os.homedir();
+const GUARDION_DIR     = path.join(HOME_DIR, '.guardion');
+const CONFIG_JSON      = path.join(GUARDION_DIR, 'config.json');
+const CURRENT_SESSION  = path.join(GUARDION_DIR, 'current-session');
+const SESSION_DIR      = path.join(GUARDION_DIR, 'sessions');
+const SETTINGS_PATH    = path.join(HOME_DIR, '.claude', 'settings.json');
+
+// ── Config ───────────────────────────────────────────────────────────────────
+
+function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_JSON, 'utf8'));
+  } catch {
+    return {
+      tier:        process.env.GUARDION_TIER        || 'hooks',
+      api_url:     process.env.GUARDION_API_URL     || 'https://api.guardion.ai',
+      policy:      process.env.GUARDION_POLICY      || '',
+      application: process.env.GUARDION_APPLICATION || 'claude-code',
+    };
+  }
+}
+
+// ── Token ────────────────────────────────────────────────────────────────────
+
+function resolveToken() {
+  if (process.env.GUARDION_TOKEN) return process.env.GUARDION_TOKEN.trim();
+  if (process.platform === 'darwin') {
+    try {
+      const t = execFileSync('security',
+        ['find-generic-password', '-s', 'guardion', '-a', 'token', '-w'],
+        { timeout: 1000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+      ).trim();
+      if (t) return t;
+    } catch { /* not found */ }
+  }
+  for (const p of ['/etc/guardion/token', path.join(GUARDION_DIR, 'token')]) {
+    try {
+      const t = fs.readFileSync(p, 'utf8').trim();
+      if (t) return t;
+    } catch { /* absent */ }
+  }
+  return '';
+}
+
+// ── Session files ────────────────────────────────────────────────────────────
+
+function writeCurrentSession(id) {
+  try {
+    fs.mkdirSync(GUARDION_DIR, { recursive: true });
+    const tmp = CURRENT_SESSION + '.tmp';
+    fs.writeFileSync(tmp, id, 'utf8');
+    fs.renameSync(tmp, CURRENT_SESSION);
+  } catch { /* non-critical */ }
+}
+
+function readCurrentSession() {
+  try { return fs.readFileSync(CURRENT_SESSION, 'utf8').trim(); } catch { return ''; }
+}
+
+function deleteCurrentSession() {
+  try { fs.unlinkSync(CURRENT_SESSION); } catch { /* gone */ }
+}
+
+function writeSessionMeta(id, meta) {
+  try {
+    fs.mkdirSync(SESSION_DIR, { recursive: true });
+    fs.writeFileSync(path.join(SESSION_DIR, `${id}.json`), JSON.stringify(meta, null, 2), 'utf8');
+  } catch { /* non-critical */ }
+}
+
+function deleteSessionMeta(id) {
+  if (!id) return;
+  try { fs.unlinkSync(path.join(SESSION_DIR, `${id}.json`)); } catch { /* gone */ }
+}
+
+// ── Full-tier: settings.json rewrite ─────────────────────────────────────────
+// Injects x-guardion-trace-id (and optionally x-guardion-metadata) into
+// ANTHROPIC_CUSTOM_HEADERS so the gateway correlates LLM calls to this session.
+// Written atomically (tmp → rename) to avoid partial-write corruption.
+
+function injectTraceHeaders(sessionId, metadata) {
+  try {
+    const raw      = fs.readFileSync(SETTINGS_PATH, 'utf8');
+    const settings = JSON.parse(raw);
+    settings.env   = settings.env || {};
+
+    const existing = (settings.env.ANTHROPIC_CUSTOM_HEADERS || '').split('\n');
+    const filtered = existing.filter(l =>
+      !l.startsWith('x-guardion-trace-id:') &&
+      !l.startsWith('x-guardion-metadata:')
+    );
+
+    filtered.push(`x-guardion-trace-id: ${sessionId}`);
+    if (metadata) {
+      const b64 = Buffer.from(JSON.stringify(metadata)).toString('base64');
+      filtered.push(`x-guardion-metadata: ${b64}`);
+    }
+
+    settings.env.ANTHROPIC_CUSTOM_HEADERS = filtered.join('\n');
+    settings.env.GUARDION_TRACE_ID        = sessionId;
+
+    const tmp = SETTINGS_PATH + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    fs.renameSync(tmp, SETTINGS_PATH);
+  } catch (e) {
+    process.stderr.write(`[guardion] settings rewrite error: ${e.message}\n`);
+  }
+}
+
+// ── HTTP POST ────────────────────────────────────────────────────────────────
+
+function postEvent(apiUrl, token, payload, timeoutMs) {
+  return new Promise(resolve => {
+    let url;
+    try { url = new URL('/v1/hooks/events', apiUrl); } catch { return resolve(); }
+
+    const transport = url.protocol === 'https:' ? https : http;
+    const body      = JSON.stringify(payload);
+
+    const req = transport.request({
+      hostname: url.hostname,
+      port:     url.port || (url.protocol === 'https:' ? 443 : 80),
+      path:     url.pathname,
+      method:   'POST',
+      headers:  {
+        'Content-Type':   'application/json',
+        'Authorization':  `Bearer ${token}`,
+        'Content-Length': Buffer.byteLength(body),
+      },
+      timeout: timeoutMs,
+    }, res => { res.resume(); res.on('end', resolve); });
+
+    req.on('error',   resolve);
+    req.on('timeout', () => { req.destroy(); resolve(); });
+    req.write(body);
+    req.end();
+  });
+}
+
+// ── Tool inventory snapshot ──────────────────────────────────────────────────
+// Sends the local tool inventory (skills, MCP servers, plugins, built-ins) to
+// Guard API at /v1/guard for scanning + storage in ai_tool_inventory.
+// Fire-and-forget; never blocks or fails the session.
+
+function postInventorySnapshot(apiUrl, token, payload, timeoutMs) {
+  return new Promise(resolve => {
+    let url;
+    try { url = new URL('/v1/guard', apiUrl); } catch { return resolve(); }
+
+    const transport = url.protocol === 'https:' ? https : http;
+    const body      = JSON.stringify(payload);
+
+    const req = transport.request({
+      hostname: url.hostname,
+      port:     url.port || (url.protocol === 'https:' ? 443 : 80),
+      path:     url.pathname,
+      method:   'POST',
+      headers:  {
+        'Content-Type':   'application/json',
+        'Authorization':  `Bearer ${token}`,
+        'Content-Length': Buffer.byteLength(body),
+      },
+      timeout: timeoutMs,
+    }, res => { res.resume(); res.on('end', resolve); });
+
+    req.on('error',   resolve);
+    req.on('timeout', () => { req.destroy(); resolve(); });
+    req.write(body);
+    req.end();
+  });
+}
+
+function collectInventory(cwd, inventoryConfig) {
+  try {
+    const { collectLocalTools } = require('./tool-scanner.cjs');
+    return collectLocalTools(cwd || process.cwd(), inventoryConfig || {});
+  } catch {
+    return [];
+  }
+}
+
+// ── Metadata ─────────────────────────────────────────────────────────────────
+
+function collectMetadata(payload) {
+  try {
+    const { collectMetadata: collect } = require('../../../core/metadata.cjs');
+    return collect(payload);
+  } catch {
+    return { session_id: payload.session_id || null, cwd: payload.cwd || process.cwd() };
+  }
+}
+
+// ── Enforcement (P2): synchronous Guard eval + Claude Code hook decision ──────
+// PreToolUse scans the tool INPUT and can deny/ask; PostToolUse scans the tool
+// OUTPUT and can block. This is the Claude-Code-native equivalent of AGT's MCP
+// gateway dual-stage pipeline (intercept_tool_call / intercept_tool_response) —
+// no proxy needed. Fires for native AND mcp__* tools.
+
+function postGuardEval(apiUrl, token, payload, timeoutMs) {
+  return new Promise(resolve => {
+    let url;
+    try { url = new URL('/v1/guard', apiUrl); } catch { return resolve(null); }
+    const transport = url.protocol === 'https:' ? https : http;
+    const body = JSON.stringify(payload);
+    const req = transport.request({
+      hostname: url.hostname,
+      port:     url.port || (url.protocol === 'https:' ? 443 : 80),
+      path:     url.pathname,
+      method:   'POST',
+      headers:  {
+        'Content-Type':   'application/json',
+        'Authorization':  `Bearer ${token}`,
+        'Content-Length': Buffer.byteLength(body),
+      },
+      timeout: timeoutMs,
+    }, res => {
+      let data = '';
+      res.setEncoding('utf8');
+      res.on('data', c => { data += c; });
+      res.on('end', () => { try { resolve(JSON.parse(data)); } catch { resolve(null); } });
+    });
+    req.on('error',   () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+    req.write(body);
+    req.end();
+  });
+}
+
+// Pure decision/mapping logic lives in enforce.cjs (testable; this file reads
+// stdin + sets a timer on load, so it can't be required from tests).
+const { toolMessage, enforceDecision } = require('./enforce.cjs');
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+const config     = loadConfig();
+const timeoutMs  = (config.hooks && config.hooks.timeout_ms) || 3000;
+
+// Hard exit — never hang Claude Code
+setTimeout(() => process.exit(0), timeoutMs + 1500);
+
+let rawInput = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { rawInput += chunk; });
+process.stdin.on('end', async () => {
+  let payload;
+  try { payload = JSON.parse(rawInput); } catch { return process.exit(0); }
+
+  const token = resolveToken();
+  if (!token) return process.exit(0);
+
+  const event = payload.hook_event_name || payload.event || '';
+
+  // Attach policy + application to every event
+  if (config.policy)      payload.policy      = config.policy;
+  if (config.application) payload.application = config.application;
+
+  // ── P2: synchronous enforcement for tool input/output ──────────────────────
+  // OPT-IN: set config.enforce=true to block/warn on tool input+output. Default
+  // off (observability-first) so day-one false positives can't block real work.
+  // The /v1/guard call also logs, so we skip the separate event post here.
+  if (config.enforce === true && (event === 'PreToolUse' || event === 'PostToolUse')) {
+    const res = await postGuardEval(config.api_url, token, {
+      application: payload.application || 'claude-code',
+      policy:      config.policy || undefined,
+      session:     payload.session_id || readCurrentSession() || undefined,
+      messages:    [toolMessage(event, payload)],
+      log:         true,
+    }, timeoutMs);
+    const out = enforceDecision(event, res, config.fail_closed === true);
+    if (out) process.stdout.write(JSON.stringify(out));
+    return process.exit(0);
+  }
+
+  if (event === 'SessionStart') {
+    const meta      = collectMetadata(payload);
+    const sessionId = payload.session_id || meta.session_id || `gs-${Date.now()}`;
+
+    payload.trace_id = sessionId;
+    payload.metadata = meta;
+
+    writeCurrentSession(sessionId);
+    writeSessionMeta(sessionId, meta);
+
+    // Full tier: inject trace-id into ANTHROPIC_CUSTOM_HEADERS so the gateway
+    // can correlate every subsequent LLM call to this session
+    if (config.tier === 'full') {
+      injectTraceHeaders(sessionId, meta);
+    }
+
+    // Tool inventory snapshot — scan local skills/MCP/plugins/built-ins and
+    // send to Guard API for scanning + inventory storage (fire-and-forget).
+    const inv = config.inventory || {};
+    if (inv.enabled !== false) {
+      const tools = collectInventory(payload.cwd, inv);
+      if (tools.length > 0) {
+        // Rug-pull pin (P1): attach prev_* fingerprints from the local pin so the
+        // server flags a changed tool description as drift. Never throws.
+        try {
+          const { pinAndEnrich } = require('../../../core/fingerprint.cjs');
+          pinAndEnrich(tools, path.join(GUARDION_DIR, 'fingerprints.json'));
+        } catch { /* fingerprint pin is best-effort */ }
+        await postInventorySnapshot(config.api_url, token, {
+          tools,
+          session:         sessionId,
+          policy:          config.policy || undefined,
+          application:     config.application || 'claude-code',
+          log:             true,
+          snapshot_source: 'plugin_scan',
+        }, timeoutMs);
+      }
+    }
+
+  } else if (event === 'SessionEnd') {
+    const sessionId = payload.session_id || readCurrentSession();
+    payload.trace_id = sessionId;
+    deleteCurrentSession();
+    deleteSessionMeta(sessionId);
+
+  } else {
+    const traceId = process.env.GUARDION_TRACE_ID || readCurrentSession();
+    if (traceId) payload.trace_id = traceId;
+  }
+
+  await postEvent(config.api_url, token, payload, timeoutMs);
+  process.exit(0);
+});

package/dist/connectors/claude-code/hooks/tool-scanner.cjs

@@ -0,0 +1,272 @@
+'use strict';
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const HOME = os.homedir();
+
+// ── SKILL.md parser ──────────────────────────────────────────────────────────
+// Parse YAML frontmatter (---\nkey: value\n---) from a SKILL.md file.
+// Returns { name, description } or null. Never throws.
+function parseSkillFrontmatter(content) {
+  try {
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!match) return null;
+    const front = match[1];
+    const name = (front.match(/^name:\s*(.+)$/m) || [])[1]?.trim();
+    // description can be multi-line (|  or |-  syntax) — grab just the first line after |-
+    const descMatch = front.match(/^description:\s*(.+)$/m)
+                   || front.match(/^description:\s*[|>-]*\s*\n\s+(.+)$/m);
+    const description = descMatch ? descMatch[1].trim() : null;
+    return { name: name || null, description: description || null };
+  } catch {
+    return null;
+  }
+}
+
+// ── Skills ───────────────────────────────────────────────────────────────────
+function collectSkills(cwd) {
+  const tools = [];
+  const skillRoots = [
+    path.join(HOME, '.claude', 'skills'),
+    path.join(cwd, '.claude', 'skills'),
+    // plugin cache skills
+    path.join(HOME, '.claude', 'plugins', 'cache'),
+    path.join(HOME, '.claude', 'plugins', 'marketplaces'),
+  ];
+
+  for (const root of skillRoots) {
+    try {
+      // Recursively find SKILL.md files (max depth 6 to avoid runaway)
+      const found = findFiles(root, 'SKILL.md', 6);
+      for (const skillPath of found) {
+        try {
+          const content = fs.readFileSync(skillPath, 'utf8');
+          const meta    = parseSkillFrontmatter(content);
+          if (!meta) continue;
+          const name = meta.name || path.basename(path.dirname(skillPath));
+          tools.push({
+            name,
+            description:     meta.description || `Skill: ${name}`,
+            server:          'skill',
+            source:          'skill',
+            snapshot_source: 'plugin_scan',
+          });
+        } catch { /* skip unreadable files */ }
+      }
+    } catch { /* root dir absent */ }
+  }
+  return dedup(tools, t => `skill:${t.name}`);
+}
+
+// ── MCP servers ──────────────────────────────────────────────────────────────
+function collectMCPServers(cwd) {
+  const tools = [];
+  const configPaths = [
+    path.join(HOME, '.claude', 'settings.json'),
+    path.join(cwd, '.mcp.json'),
+    path.join(cwd, '.claude', 'settings.json'),
+  ];
+
+  // Also scan plugin cache .mcp.json files
+  try {
+    const cacheRoot = path.join(HOME, '.claude', 'plugins', 'cache');
+    const mcpFiles  = findFiles(cacheRoot, '.mcp.json', 5);
+    configPaths.push(...mcpFiles);
+  } catch { /* absent */ }
+
+  for (const cfgPath of configPaths) {
+    try {
+      const raw  = fs.readFileSync(cfgPath, 'utf8');
+      const json = JSON.parse(raw);
+      const mcpServers = json.mcpServers || (cfgPath.endsWith('.mcp.json') ? json : null);
+      if (!mcpServers || typeof mcpServers !== 'object') continue;
+
+      for (const [serverName, serverCfg] of Object.entries(mcpServers)) {
+        const transport = serverCfg.type || (serverCfg.command ? 'stdio' : 'http');
+        const endpoint  = serverCfg.url || serverCfg.command || 'unknown';
+        tools.push({
+          name:            serverName,
+          description:     `MCP server (${transport}): ${endpoint}`,
+          server:          serverName,
+          source:          'mcp',
+          snapshot_source: 'plugin_scan',
+        });
+      }
+    } catch { /* skip invalid files */ }
+  }
+  return dedup(tools, t => `mcp:${t.name}`);
+}
+
+// ── Plugin agents ─────────────────────────────────────────────────────────────
+// Report EVERY installed plugin in the Claude Code plugin cache — not only the
+// ones declaring hooks — so the inventory reflects the agent's full installed-
+// plugin surface. For each plugin we record what it provides (hooks / mcp /
+// skills / commands / agents) both from the manifest and from the on-disk
+// layout (Claude Code auto-discovers those directories).
+//
+// Identity is the install directory: a plugin that ships both a root and a
+// `.claude-plugin/` manifest counts once, while distinct installs (different
+// cache locations or versions) stay separate instead of being silently merged.
+function collectPluginTools(cacheRootOverride) {
+  const tools = [];
+  const cacheRoot = cacheRootOverride || path.join(HOME, '.claude', 'plugins', 'cache');
+
+  let manifestFiles;
+  try { manifestFiles = findFiles(cacheRoot, 'plugin.json', 6); }
+  catch { return tools; }
+
+  // installDir -> aggregated info (collapses a plugin's root + .claude-plugin manifests)
+  const byInstall = new Map();
+
+  for (const mPath of manifestFiles) {
+    // Ignore stray manifests bundled inside a plugin's dependencies.
+    if (mPath.includes(`${path.sep}node_modules${path.sep}`)) continue;
+    try {
+      const manifest = JSON.parse(fs.readFileSync(mPath, 'utf8'));
+
+      // Install dir = the plugin root (strip a trailing .claude-plugin/).
+      let installDir = path.dirname(mPath);
+      if (path.basename(installDir) === '.claude-plugin') installDir = path.dirname(installDir);
+
+      // Marketplace = first path segment under the cache root (e.g. claude-plugins-official).
+      const rel = path.relative(cacheRoot, installDir);
+      const marketplace = (rel.split(path.sep)[0]) || 'local';
+
+      const entry = byInstall.get(installDir) || {
+        marketplace,
+        name:        path.basename(installDir),
+        version:     '',
+        description: '',
+        caps:        new Set(),
+        mcpServers:  {},
+      };
+      if (manifest.name)        entry.name        = manifest.name;
+      if (manifest.version)     entry.version     = manifest.version;
+      if (manifest.description) entry.description = manifest.description;
+
+      // Capabilities — from the manifest …
+      if (manifest.hooks   && typeof manifest.hooks === 'object')   entry.caps.add('hooks');
+      if (manifest.commands)                                        entry.caps.add('commands');
+      if (manifest.agents)                                          entry.caps.add('agents');
+      if (manifest.mcpServers && typeof manifest.mcpServers === 'object') {
+        entry.caps.add('mcp');
+        Object.assign(entry.mcpServers, manifest.mcpServers);
+      }
+      // … and from the on-disk layout (auto-discovered directories / files).
+      for (const [dir, cap] of [['hooks', 'hooks'], ['commands', 'commands'], ['agents', 'agents'], ['skills', 'skills']]) {
+        try { if (fs.existsSync(path.join(installDir, dir))) entry.caps.add(cap); } catch { /* ignore */ }
+      }
+      try { if (fs.existsSync(path.join(installDir, '.mcp.json'))) entry.caps.add('mcp'); } catch { /* ignore */ }
+
+      byInstall.set(installDir, entry);
+    } catch { /* skip invalid manifests */ }
+  }
+
+  for (const p of byInstall.values()) {
+    const capabilities = [...p.caps].sort();
+    const verLabel = p.version ? `@${p.version}` : '';
+    tools.push({
+      name:            p.name,
+      description:     p.description
+        ? `${p.description} [${capabilities.join(', ') || 'no declared components'}]`
+        : `Plugin ${p.name}${verLabel} [${capabilities.join(', ') || 'no declared components'}] from ${p.marketplace}`,
+      server:          'plugin',
+      source:          'plugin',
+      snapshot_source: 'plugin_scan',
+      // Structured metadata (Guard's ToolDefinition allows extra fields).
+      version:         p.version || undefined,
+      marketplace:     p.marketplace,
+      capabilities,
+      has_hooks:       p.caps.has('hooks'),
+      has_mcp:         p.caps.has('mcp'),
+      has_skills:      p.caps.has('skills'),
+    });
+    // MCP servers declared inline in the plugin manifest → their own entries.
+    for (const [serverName, serverCfg] of Object.entries(p.mcpServers)) {
+      const cfg       = serverCfg && typeof serverCfg === 'object' ? serverCfg : {};
+      const transport = cfg.type || (cfg.command ? 'stdio' : 'http');
+      const endpoint  = cfg.url || cfg.command || 'plugin';
+      tools.push({
+        name:            serverName,
+        description:     `Plugin MCP server (${transport}): ${endpoint}`,
+        server:          serverName,
+        source:          'mcp',
+        snapshot_source: 'plugin_scan',
+      });
+    }
+  }
+
+  // Plugins are unique per install (name:version:marketplace); MCP entries dedup by name.
+  return dedup(tools, t => t.source === 'plugin'
+    ? `plugin:${t.name}:${t.version || ''}:${t.marketplace || ''}`
+    : `mcp:${t.name}`);
+}
+
+// ── Built-in Claude Code tools ────────────────────────────────────────────────
+function builtinTools() {
+  return [
+    { name: 'Read',         description: 'Read file contents from the local filesystem' },
+    { name: 'Write',        description: 'Write content to a file on the local filesystem' },
+    { name: 'Edit',         description: 'Make targeted edits to a specific file' },
+    { name: 'MultiEdit',    description: 'Make multiple targeted edits to one or more files' },
+    { name: 'Bash',         description: 'Execute a bash command in the shell environment' },
+    { name: 'Glob',         description: 'Find files and directories using glob patterns' },
+    { name: 'Grep',         description: 'Search for patterns within file contents' },
+    { name: 'LS',           description: 'List files and directories at a path' },
+    { name: 'WebFetch',     description: 'Fetch content from a URL' },
+    { name: 'WebSearch',    description: 'Search the web for information' },
+    { name: 'TodoRead',     description: 'Read the current todo list for this session' },
+    { name: 'TodoWrite',    description: 'Create or update the todo list for this session' },
+    { name: 'NotebookRead', description: 'Read and display a Jupyter notebook' },
+    { name: 'NotebookEdit', description: 'Edit a cell in a Jupyter notebook' },
+    { name: 'Agent',        description: 'Spawn a subagent to handle a complex subtask' },
+  ].map(t => ({
+    ...t,
+    server:          'claude-code',
+    source:          'native',
+    snapshot_source: 'plugin_scan',
+  }));
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function findFiles(dir, filename, maxDepth) {
+  const results = [];
+  if (maxDepth <= 0) return results;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return results; }
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findFiles(fullPath, filename, maxDepth - 1));
+    } else if (entry.name === filename) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function dedup(tools, keyFn) {
+  const seen = new Set();
+  return tools.filter(t => {
+    const k = keyFn(t);
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+function collectLocalTools(cwd, inventoryConfig) {
+  const cfg = inventoryConfig || {};
+  const tools = [];
+  try {
+    if (cfg.scan_skills   !== false) tools.push(...collectSkills(cwd || process.cwd()));
+    if (cfg.scan_mcp      !== false) tools.push(...collectMCPServers(cwd || process.cwd()));
+    if (cfg.scan_plugins  !== false) tools.push(...collectPluginTools());
+    if (cfg.scan_builtins !== false) tools.push(...builtinTools());
+  } catch { /* never crash the hook */ }
+  return tools;
+}
+
+module.exports = { collectLocalTools, parseSkillFrontmatter, collectSkills, collectMCPServers, collectPluginTools, builtinTools };