@heretek-ai/epistemic-swarm 0.2.0 → 0.2.2

package/.claude-plugin/marketplace.json

@@ -1,14 +1,41 @@
 {
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "heretek-official",
-  "owner": "Heretek AI",
-  "description": "Official plugins and agent harnesses from Heretek AI",
-  "plugins": {
-    "epistemic-swarm": {
-      "source": {
-        "source": "github",
-        "repo": "Heretek-AI/IUMBTEMS"
+  "description": "Official high-integrity research agents and epistemic skills from Heretek AI",
+  "owner": {
+    "name": "Heretek AI",
+    "email": "dev@heretek.ai"
+  },
+  "plugins": [
+    {
+      "name": "epistemic-swarm",
+      "description": "High-Integrity Dialectic Research Agent Harness enforcing verified empirical evidence over parametric hallucination.",
+      "author": {
+        "name": "Heretek AI"
       },
-      "description": "High-Integrity Dialectic Research Agent Harness for Claude Code"
+      "category": "research",
+      "source": "./",
+      "homepage": "https://github.com/Heretek-AI/IUMBTEMS"
+    },
+    {
+      "name": "socratic-grilling",
+      "description": "Matt Pocock-style Socratic interrogation, premise inversion, and lateral exploration skill for Claude Code.",
+      "author": {
+        "name": "Heretek AI"
+      },
+      "category": "agents",
+      "source": "./plugins/socratic-grilling",
+      "homepage": "https://github.com/Heretek-AI/IUMBTEMS"
+    },
+    {
+      "name": "research-cache",
+      "description": "Content-addressed SHA256 Markdown source hashing and verbatim quote verification engine.",
+      "author": {
+        "name": "Heretek AI"
+      },
+      "category": "research",
+      "source": "./plugins/research-cache",
+      "homepage": "https://github.com/Heretek-AI/IUMBTEMS"
     }
-  }
+  ]
 }

package/.claude-plugin/plugin.json

@@ -1,58 +1,64 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "High-Integrity Dialectic Research Agent Harness for Claude Code enforcing empirical evidence over parametric hallucination.",
-  "author": "Heretek AI",
+  "author": {
+    "name": "Heretek AI",
+    "email": "dev@heretek.ai"
+  },
   "license": "Apache-2.0",
   "repository": "https://github.com/Heretek-AI/IUMBTEMS",
+  "homepage": "https://github.com/Heretek-AI/IUMBTEMS#readme",
+  "userConfig": {
+    "brave_api_key": {
+      "type": "string",
+      "title": "Brave Search API Key",
+      "description": "API key for Brave Search discovery (optional; zero-key DuckDuckGo fallback is used when unset)",
+      "sensitive": true,
+      "required": false
+    },
+    "firecrawl_api_key": {
+      "type": "string",
+      "title": "Firecrawl API Key",
+      "description": "API key for Firecrawl deep web extraction (optional; zero-key readability fallback is used when unset)",
+      "sensitive": true,
+      "required": false
+    },
+    "firecrawl_api_url": {
+      "type": "string",
+      "title": "Firecrawl API URL",
+      "description": "Endpoint for Firecrawl API or self-hosted instance",
+      "default": "https://api.firecrawl.dev",
+      "required": false
+    },
+    "searxng_url": {
+      "type": "string",
+      "title": "SearXNG URL",
+      "description": "Endpoint for self-hosted SearXNG metasearch instance",
+      "default": "http://localhost:8080",
+      "required": false
+    }
+  },
   "mcpServers": {
     "brave-search": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
-      "env": {
-        "BRAVE_SEARCH_API_KEY": "${BRAVE_SEARCH_API_KEY}"
-      }
+      "command": "python3",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/config/mcp_launcher.py", "brave-search"]
     },
     "firecrawl": {
-      "command": "npx",
-      "args": ["-y", "firecrawl-mcp"],
-      "env": {
-        "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}",
-        "FIRECRAWL_API_URL": "${FIRECRAWL_API_URL:-http://localhost:3002}"
-      }
+      "command": "python3",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/config/mcp_launcher.py", "firecrawl"]
     },
     "searxng": {
       "command": "python3",
-      "args": ["${PLUGIN_DIR}/config/searxng_mcp.py"],
-      "env": {
-        "SEARXNG_URL": "${SEARXNG_URL:-http://localhost:8080}"
-      }
+      "args": ["${CLAUDE_PLUGIN_ROOT}/config/mcp_launcher.py", "searxng"]
     }
   },
   "skills": [
     "./skills/grilling",
-    "./skills/research-cache"
-  ],
-  "configuration": {
-    "SEARXNG_URL": {
-      "type": "string",
-      "description": "SearXNG metasearch instance URL",
-      "default": "http://localhost:8080"
-    },
-    "FIRECRAWL_API_URL": {
-      "type": "string",
-      "description": "Firecrawl API endpoint for JS/Markdown extraction",
-      "default": "http://localhost:3002"
-    },
-    "FIRECRAWL_API_KEY": {
-      "type": "string",
-      "description": "Firecrawl API Key (optional for self-hosted instances)",
-      "default": ""
-    },
-    "BRAVE_SEARCH_API_KEY": {
-      "type": "string",
-      "description": "Brave Search API Key for discovery",
-      "default": ""
-    }
-  }
+    "./skills/research_cache",
+    "./skills/epistemic_search",
+    "./skills/swarm_config",
+    "./skills/code_audit",
+    "./skills/oss_scout"
+  ]
 }

package/MARKETPLACE.md

@@ -0,0 +1,93 @@
+# Heretek AI Claude Code Marketplace 🏪
+
+Official marketplace catalog for Claude Code plugins, skills, and autonomous agent harnesses developed by [Heretek AI](https://github.com/Heretek-AI).
+
+[![Claude Code Compatible](https://img.shields.io/badge/Claude_Code-2.1+-blue.svg)](https://claude.com)
+[![Marketplace Validated](https://img.shields.io/badge/Marketplace-Validated_Strict-success.svg)](https://github.com/Heretek-AI/IUMBTEMS/actions/workflows/validate-marketplace.yml)
+[![npm version](https://img.shields.io/npm/v/@heretek-ai/epistemic-swarm.svg)](https://www.npmjs.com/package/@heretek-ai/epistemic-swarm)
+
+---
+
+## 🚀 Quick Start: Adding the Marketplace
+
+To register the **`heretek-official`** marketplace in Claude Code, run:
+
+```bash
+claude plugin marketplace add Heretek-AI/IUMBTEMS
+```
+
+Verify that the marketplace is configured:
+```bash
+claude plugin marketplace list
+```
+
+---
+
+## 📦 Available Plugins
+
+| Plugin Name | Category | Description | Install Command |
+|---|---|---|---|
+| **`epistemic-swarm`** | `research` | **Flagship Swarm Harness**: Multi-agent dialectic research harness pairing Agent Alpha (Thesis) against Agent Beta (Red Team), audited by an Epistemic Auditor with verbatim empirical quote validation. | `claude plugin install epistemic-swarm@heretek-official` |
+| **`socratic-grilling`** | `agents` | **Socratic Ideation**: Matt Pocock-style Socratic interrogation, premise inversion, and lateral exploration skill. | `claude plugin install socratic-grilling@heretek-official` |
+| **`research-cache`** | `research` | **Source Hasher**: Content-addressed SHA256 Markdown source hashing and verbatim quote verification engine. | `claude plugin install research-cache@heretek-official` |
+
+---
+
+## 🛠️ Plugin Details & Component Breakdown
+
+### 1. `epistemic-swarm` (Flagship Harness)
+- **Manifest**: [`.claude-plugin/plugin.json`](file:///.claude-plugin/plugin.json)
+- **Components**:
+  - **Skills**: `skills/grilling`, `skills/research_cache`, `skills/epistemic_search`
+  - **Hooks**: `hooks/hooks.json` (`PreToolUse` hook intercepting ungrounded `WebSearch` and `WebFetch` to enforce verifiable SHA-256 caching)
+  - **Zero-Key Search**: DuckDuckGo Lite search and automated content-addressed document caching out of the box (zero API key required).
+  - **Safe MCP Servers & Accelerators**:
+    - `brave-search`: Optional Brave SERP discovery (falls back smoothly to DuckDuckGo when unconfigured).
+    - `firecrawl`: Optional Firecrawl JS extraction (falls back smoothly to clean readability reader when unconfigured).
+    - `searxng`: Optional self-hosted metasearch instance proxy.
+  - **System Prompts**: Base Epistemic System Override, Agent Alpha, Agent Beta, Epistemic Auditor, Orchestrator.
+- **Install & Configuration**:
+  ```bash
+  claude plugin install epistemic-swarm@heretek-official
+  # Configure optional API keys and endpoints interactively:
+  claude plugin configure epistemic-swarm
+  # Or inside Claude Code interactive session: /plugin configure
+  ```
+
+### 2. `socratic-grilling` (Modular Skill)
+- **Manifest**: [`plugins/socratic-grilling/.claude-plugin/plugin.json`](file:///plugins/socratic-grilling/.claude-plugin/plugin.json)
+- **Components**:
+  - **Skill**: `skills/grilling` (`/grilling` slash command and interactive decision tree).
+- **Install**:
+  ```bash
+  claude plugin install socratic-grilling@heretek-official
+  ```
+
+### 3. `research-cache` (Modular Tool)
+- **Manifest**: [`plugins/research-cache/.claude-plugin/plugin.json`](file:///plugins/research-cache/.claude-plugin/plugin.json)
+- **Components**:
+  - **Skill & Engine**: `skills/research-cache` (Content-addressed SHA256 raw source storage and quote validation).
+- **Install**:
+  ```bash
+  claude plugin install research-cache@heretek-official
+  ```
+
+---
+
+## 🔍 Inspecting Installed Plugins
+
+To view installed plugins and their active components:
+```bash
+claude plugin list
+claude plugin details epistemic-swarm@heretek-official
+```
+
+To update all installed plugins to their latest versions:
+```bash
+claude plugin update epistemic-swarm
+```
+
+To uninstall:
+```bash
+claude plugin uninstall epistemic-swarm
+```

package/README.md

@@ -3,6 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@heretek-ai/epistemic-swarm.svg)](https://www.npmjs.com/package/@heretek-ai/epistemic-swarm)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![CI/CD](https://github.com/Heretek-AI/IUMBTEMS/actions/workflows/publish.yml/badge.svg)](https://github.com/Heretek-AI/IUMBTEMS/actions)
+[![Marketplace Validated](https://github.com/Heretek-AI/IUMBTEMS/actions/workflows/validate-marketplace.yml/badge.svg)](https://github.com/Heretek-AI/IUMBTEMS/actions)
 
 > **High-Integrity Dialectic Research Agent Harness**  
 > *Universal support for Claude Code, Pi (pi.dev), and OpenCode V2.*  
@@ -27,8 +28,26 @@ Modern LLMs suffer from parametric hallucination, sycophancy, and premature narr
 
 IUMBTEMS is packaged as a single universal npm package (`@heretek-ai/epistemic-swarm` with `iumbtems` binary) that runs across the three major autonomous agent platforms:
 
-### 1. Claude Code
-Install skills and MCP servers into `~/.claude/` and `~/.claude.json`:
+### 1. Claude Code (Native Marketplace & Overlay)
+
+#### Native Marketplace (Recommended)
+Add the official Heretek AI marketplace to Claude Code:
+```bash
+claude plugin marketplace add Heretek-AI/IUMBTEMS
+```
+Then install either the flagship harness or modular standalone plugins:
+```bash
+# Flagship dialectic research harness:
+claude plugin install epistemic-swarm@heretek-official
+
+# Or install standalone modular plugins:
+claude plugin install socratic-grilling@heretek-official
+claude plugin install research-cache@heretek-official
+```
+See [MARKETPLACE.md](MARKETPLACE.md) for full component specifications.
+
+#### CLI Overlay Installer
+Install skills and MCP servers directly into `~/.claude/` and `~/.claude.json`:
 ```bash
 npx @heretek-ai/epistemic-swarm install
 # or from local repo:
@@ -69,6 +88,16 @@ OpenCode V2 automatically registers:
 ## ⚡ CLI Command Reference
 
 ```bash
+# Inspect or update active configuration (search engine, depth, mode)
+iumbtems config
+iumbtems config --engine duckduckgo --depth 3 --mode audit
+
+# Run dialectic codebase architecture & security audit
+iumbtems audit "runner/ and skills/ concurrency and injection security"
+
+# Scout open-source software, mature libraries & clean-room blueprints
+iumbtems scout "Zero-dependency Raft consensus implementations in Rust"
+
 # Run the autonomous dialectic research swarm
 iumbtems run "Sub-millisecond ZK state updates on L1 rollups"
 
@@ -82,6 +111,14 @@ iumbtems doctor
 iumbtems test
 ```
 
+### Specialized Dialectic Skills & Slash Commands
+- **`/swarm-config`**: Interactive tuning of search engines (DuckDuckGo, Brave, Firecrawl, SearXNG), iteration depth, divergence thresholds, and operating modes.
+- **`/code-audit`**: Dialectic codebase review pairing a Structural Architect (thesis) with a Vulnerability Red-Teamer (antithesis) enforcing line-number proofs (`file:///path#L10-25`).
+- **`/oss-scout`**: Evaluates GitHub repositories, package ecosystems (npm, crates.io, PyPI), license contamination (GPL/AGPL copyleft vs MIT/Apache), and outputs clean-room re-implementation blueprints.
+- **`/grilling`**: Socratic assumption-inversion and Matt Pocock-style design tree frontier discovery.
+- **`epistemic_search`**: Zero-key DuckDuckGo Lite search and content-addressed fetch with automatic SHA-256 caching.
+
+
 ---
 
 ## 🏷️ Epistemic Tagging Taxonomy

package/bin/cli.js

@@ -25,9 +25,13 @@ Usage:
   npx @heretek-ai/epistemic-swarm <command> [options]
 
 Commands:
+  config [options]      Inspect or modify swarm parameters (engine, depth, mode)
+  audit "<target>"      Run dialectic codebase architectural & security audit
+  scout "<feature>"     Scout open-source software, libraries & clean-room blueprints
   run "<objective>"     Run the dialectic multi-agent research swarm
   grill                 Launch interactive Socratic decision tree framing
   install               Install skills & MCP servers into ~/.claude/
+  marketplace           Show Claude Code marketplace catalog & install commands
   test                  Run test suite for hashing, state machine & auditor
   doctor                Check environment requirements (Claude Code, Pi, OpenCode)
   help                  Show this help message
@@ -40,9 +44,15 @@ Platform Extensions:
 Options:
   --mock-claude         Run swarm with synthetic mock responses (zero API cost)
   --frontier <file>     Path to settled frontier.json from Socratic grilling
+  --mode <mode>         Operating mode (research, audit, scout, hybrid)
+  --engine <engine>     Search engine (duckduckgo, brave, firecrawl, searxng)
+  --depth <n>           Max dialectic iterations (1-4)
   --dir <path>          Path to .research workspace directory (default: .research)
 
 Examples:
+  iumbtems config --engine duckduckgo --depth 3
+  iumbtems audit "runner/ and skills/ concurrency & security"
+  iumbtems scout "Zero-dependency Raft consensus in Rust"
   iumbtems run "Verify sub-millisecond ZK prover latency"
   iumbtems grill --objective "Rollup architecture trade-offs"
   iumbtems doctor
@@ -75,6 +85,31 @@ function runBash(scriptRelPath, extraArgs = []) {
 }
 
 switch (command) {
+  case 'config': {
+    runPython('skills/swarm_config/configure.py', args.slice(1));
+    break;
+  }
+
+  case 'audit': {
+    const targetObj = args[1] && !args[1].startsWith('--') ? args[1] : 'Full codebase architectural and security audit';
+    const restArgs = args[1] && !args[1].startsWith('--') ? args.slice(2) : args.slice(1);
+    const forwardArgs = ['--mode', 'audit', '--objective', targetObj, ...restArgs];
+    runPython('runner/research_swarm.py', forwardArgs);
+    break;
+  }
+
+  case 'scout': {
+    const objective = args[1];
+    if (!objective || objective.startsWith('--')) {
+      console.error('Error: Please provide a feature or library to scout.');
+      console.error('Example: npx @heretek-ai/epistemic-swarm scout "Zero-dependency Raft in Rust"');
+      process.exit(1);
+    }
+    const forwardArgs = ['--mode', 'scout', '--objective', objective, ...args.slice(2)];
+    runPython('runner/research_swarm.py', forwardArgs);
+    break;
+  }
+
   case 'run': {
     const objective = args[1];
     if (!objective || objective.startsWith('--')) {
@@ -97,6 +132,29 @@ switch (command) {
     break;
   }
 
+  case 'marketplace': {
+    const mktPath = path.join(PKG_ROOT, '.claude-plugin', 'marketplace.json');
+    if (!fs.existsSync(mktPath)) {
+      console.error('Marketplace manifest not found.');
+      process.exit(1);
+    }
+    const mkt = JSON.parse(fs.readFileSync(mktPath, 'utf8'));
+    console.log(`\n🏪 CLAUDE CODE MARKETPLACE: ${mkt.name.toUpperCase()}`);
+    console.log(`================================================`);
+    console.log(`Owner:       ${mkt.owner ? mkt.owner.name : 'Unknown'} <${mkt.owner ? mkt.owner.email : ''}>`);
+    console.log(`Description: ${mkt.description}\n`);
+    console.log(`🚀 Add this marketplace to Claude Code:`);
+    console.log(`   claude plugin marketplace add Heretek-AI/IUMBTEMS\n`);
+    console.log(`📦 Available Plugins in Marketplace:`);
+    (mkt.plugins || []).forEach((p, idx) => {
+      console.log(`   ${idx + 1}. ${p.name} [${p.category || 'plugin'}]`);
+      console.log(`      Description: ${p.description}`);
+      console.log(`      Install:     claude plugin install ${p.name}@${mkt.name}`);
+      console.log(`      Configure:   claude plugin configure ${p.name}@${mkt.name}\n`);
+    });
+    break;
+  }
+
   case 'test': {
     runPython('-m', ['unittest', 'discover', '-s', 'runner/tests']);
     break;

package/config/mcp_launcher.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""
+Intelligent MCP Server Launcher & Epistemic Fallback Proxy for IUMBTEMS.
+Safely detects API keys and endpoints:
+- If keys are present (via env or userConfig): launches the official MCP server.
+- If keys are absent: smoothly provides a zero-key JSON-RPC fallback MCP server
+  backed by DuckDuckGo Lite search and content-addressed SHA256 caching.
+Prevents startup crashes and missing environment variable errors in Claude Code.
+"""
+
+import sys
+import os
+import json
+import subprocess
+import shutil
+from typing import Dict, Any, List
+
+# Add parent dir to path for imports
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+PROJECT_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
+if PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, PROJECT_ROOT)
+
+def get_config_val(key: str, default: str = "") -> str:
+    """Retrieve config from env, userConfig, or defaults."""
+    env_val = os.environ.get(key)
+    if env_val:
+        return env_val
+    # Also check user_config format
+    user_cfg_val = os.environ.get(f"CLAUDE_PLUGIN_OPTION_{key.upper()}")
+    if user_cfg_val:
+        return user_cfg_val
+    return default
+
+def run_zero_key_mcp_server(service: str):
+    """Run lightweight JSON-RPC MCP server handling search and fetch without API keys."""
+    from skills.epistemic_search.scripts.search import search_duckduckgo
+    from skills.epistemic_search.scripts.fetch import fetch_and_cache
+
+    def send_response(response: Dict[str, Any]):
+        out = json.dumps(response)
+        sys.stdout.write(f"Content-Length: {len(out)}\r\n\r\n{out}")
+        sys.stdout.flush()
+
+    def send_json(response: Dict[str, Any]):
+        # Direct newline JSON-RPC for stdio transports
+        sys.stdout.write(json.dumps(response) + "\n")
+        sys.stdout.flush()
+
+    while True:
+        try:
+            line = sys.stdin.readline()
+            if not line:
+                break
+            line = line.strip()
+            if not line:
+                continue
+
+            # Check if line is Content-Length header or raw JSON
+            if line.startswith("Content-Length:"):
+                length = int(line.split(":")[1].strip())
+                # Read blank line
+                sys.stdin.readline()
+                body = sys.stdin.read(length)
+                req = json.loads(body)
+                use_headers = True
+            else:
+                req = json.loads(line)
+                use_headers = False
+
+            req_id = req.get("id")
+            method = req.get("method")
+            params = req.get("params", {})
+
+            if method == "initialize":
+                res = {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {
+                        "protocolVersion": "2024-11-05",
+                        "serverInfo": {
+                            "name": f"epistemic-{service}-fallback",
+                            "version": "0.2.1"
+                        },
+                        "capabilities": {
+                            "tools": {}
+                        }
+                    }
+                }
+            elif method == "tools/list":
+                if service == "brave-search":
+                    tools = [
+                        {
+                            "name": "brave_web_search",
+                            "description": "Web search with DuckDuckGo fallback (zero API key required). Returns verifiable search results with titles, URLs, and snippets.",
+                            "inputSchema": {
+                                "type": "object",
+                                "properties": {
+                                    "query": {"type": "string", "description": "The search query terms"},
+                                    "count": {"type": "number", "description": "Number of results (1-20)", "default": 10}
+                                },
+                                "required": ["query"]
+                            }
+                        }
+                    ]
+                elif service == "firecrawl":
+                    tools = [
+                        {
+                            "name": "firecrawl_scrape",
+                            "description": "Scrape and extract clean markdown with automatic content-addressed SHA-256 caching into .research/sources/.",
+                            "inputSchema": {
+                                "type": "object",
+                                "properties": {
+                                    "url": {"type": "string", "description": "URL to scrape and cache"}
+                                },
+                                "required": ["url"]
+                            }
+                        }
+                    ]
+                else:
+                    tools = []
+
+                res = {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {"tools": tools}
+                }
+            elif method == "tools/call":
+                tool_name = params.get("name")
+                args = params.get("arguments", {})
+
+                if tool_name in ("brave_web_search", "search"):
+                    q = args.get("query", "")
+                    count = args.get("count", 10)
+                    results = search_duckduckgo(query=q, max_results=count)
+                    text_out = json.dumps(results, indent=2)
+                    res = {
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "result": {
+                            "content": [{"type": "text", "text": text_out}]
+                        }
+                    }
+                elif tool_name in ("firecrawl_scrape", "scrape", "fetch"):
+                    target_url = args.get("url", "")
+                    content = fetch_and_cache(url=target_url)
+                    res = {
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "result": {
+                            "content": [{"type": "text", "text": content}]
+                        }
+                    }
+                else:
+                    res = {
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "error": {"code": -32601, "message": f"Tool {tool_name} not found"}
+                    }
+            elif method == "notifications/initialized":
+                continue
+            else:
+                res = {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "error": {"code": -32601, "message": f"Method {method} not handled"}
+                }
+
+            if use_headers:
+                send_response(res)
+            else:
+                send_json(res)
+
+        except Exception as e:
+            sys.stderr.write(f"[mcp-launcher] Error handling request: {e}\n")
+            break
+
+def main():
+    service = sys.argv[1] if len(sys.argv) > 1 else "brave-search"
+    npx_bin = shutil.which("npx")
+
+    if service == "brave-search":
+        api_key = get_config_val("BRAVE_SEARCH_API_KEY")
+        if api_key and npx_bin:
+            os.environ["BRAVE_SEARCH_API_KEY"] = api_key
+            os.execvp(npx_bin, [npx_bin, "-y", "@modelcontextprotocol/server-brave-search"])
+        else:
+            # Fall back to zero-key search proxy
+            run_zero_key_mcp_server("brave-search")
+
+    elif service == "firecrawl":
+        api_key = get_config_val("FIRECRAWL_API_KEY")
+        api_url = get_config_val("FIRECRAWL_API_URL", "https://api.firecrawl.dev")
+        if api_key and npx_bin:
+            os.environ["FIRECRAWL_API_KEY"] = api_key
+            os.environ["FIRECRAWL_API_URL"] = api_url
+            os.execvp(npx_bin, [npx_bin, "-y", "firecrawl-mcp"])
+        else:
+            # Fall back to zero-key readability fetcher + SHA-256 hasher
+            run_zero_key_mcp_server("firecrawl")
+
+    elif service == "searxng":
+        searxng_url = get_config_val("SEARXNG_URL", "http://localhost:8080")
+        searxng_script = os.path.join(SCRIPT_DIR, "searxng_mcp.py")
+        if os.path.exists(searxng_script):
+            os.environ["SEARXNG_URL"] = searxng_url
+            os.execvp("python3", ["python3", searxng_script])
+        else:
+            run_zero_key_mcp_server("searxng")
+    else:
+        sys.stderr.write(f"Unknown service: {service}\n")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/hooks/hooks.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "WebSearch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"WebSearch intercepted by epistemic-swarm to enforce verified citation integrity. Use epistemic search (python3 ${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/search.py \\\"<query>\\\") instead.\"}}'"
+          }
+        ]
+      },
+      {
+        "matcher": "WebFetch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"WebFetch intercepted by epistemic-swarm to enforce content-addressed caching. Use epistemic fetch (python3 ${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/fetch.py \\\"<url>\\\") which automatically stores documents in .research/sources/<sha256>.md for mathematical auditability.\"}}'"
+          }
+        ]
+      }
+    ]
+  }
+}