thumbgate 1.30.0 → 1.31.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "thumbgate",
   "description": "One 👎 becomes a hard rule the agent cannot bypass. Captures thumbs-down feedback, distills it into PreToolUse Pre-Action Checks, enforced across every future Claude Code session.",
-  "version": "1.30.0",
+  "version": "1.31.0",
   "author": {
     "name": "Igor Ganapolsky",
     "email": "ig5973700@gmail.com",

package/.well-known/mcp/server-card.json

@@ -1,6 +1,6 @@
 {
   "name": "thumbgate",
-  "version": "1.30.0",
+  "version": "1.31.0",
   "description": "ThumbGate — 👍👎 feedback that teaches your AI agent. Thumbs down a mistake, it never happens again.",
   "homepage": "https://thumbgate.ai",
   "transport": "stdio",

package/README.md

@@ -1,5 +1,7 @@
 # ThumbGate
 
+[![MCP Toplist](https://mcptoplist.com/badge/glama%2FIgorGanapolsky%2FThumbGate.svg)](https://mcptoplist.com/server/glama%2FIgorGanapolsky%2FThumbGate)
+
 <p align="center">
   <a href="https://thumbgate.ai">
     <img src="public/assets/brand/thumbgate-icon-512.png" alt="ThumbGate" width="128" height="128" />
@@ -28,6 +30,19 @@ Accepted feedback is stored as local lessons. Repeated concrete failures can bec
 npx thumbgate init   # auto-detects the supported agent and wires its integration
 ```
 
+### MCP / Glama / registry install (stdio)
+
+Directories and clients that install ThumbGate as an MCP server must start **stdio MCP**, not the HTTP API:
+
+```bash
+npx -y thumbgate serve
+```
+
+- Equivalent: `npx -y thumbgate mcp`
+- Do **not** use `npm start` for MCP — that launches the hosted HTTP API (`src/api/server.js`), not the agent-facing stdio server.
+- Canonical package metadata: `server.json` (`runtimeHint: npx` + `packageArguments: ["serve"]`), Smithery: `smithery.yaml`, maintainers: `glama.json`.
+- Product name is **ThumbGate** only (npm: `thumbgate`). Retired legacy package aliases are not active product surfaces.
+
 Works with **Claude Code, Cursor, Codex, Gemini CLI, Amp, Cline, OpenCode** and MCP-compatible agents after their integration is configured. Free tier: 2 feedback captures/day (10 total) and up to 3 active auto-promoted prevention rules. [Pro: $19/mo or $149/yr](https://thumbgate.ai/checkout/pro?utm_source=github&utm_medium=readme) is the individual tier for unlimited rules, history-aware lessons, feedback sessions, a personal dashboard, and DPO export. Enterprise is custom and scoped after intake; hosted team sync and a hosted org dashboard are not in the current general-availability runtime.
 
 [![CI](https://github.com/IgorGanapolsky/ThumbGate/actions/workflows/ci.yml/badge.svg)](https://github.com/IgorGanapolsky/ThumbGate/actions/workflows/ci.yml)
@@ -256,6 +271,11 @@ evaluation/observability—is maintained in
 architecture exists, what can fail, how it is measured and secured, how it is
 deployed, and what evidence is required before claiming it works.
 
+The full framework decision and one end-to-end RAG request—tenant authorization,
+query transformation, parent-child retrieval, hybrid fusion, reranking,
+structured generation, evaluation, and tracing—are documented in
+[`docs/RAG_PRODUCTION_ARCHITECTURE.md`](./docs/RAG_PRODUCTION_ARCHITECTURE.md).
+
 ### Retrieval & latency: local-first, zero network hops
 
 ThumbGate's latency advantage is structural, not a tuned cloud cluster: there is no retrieval service and no model on the enforcement path, so the gate decision never leaves your machine.
@@ -302,22 +322,40 @@ Each recommendation ships with the benchmark commands to run next: feedback-deri
 
 ## Install for Your Agent
 
-| Agent | Command |
-|-------|---------|
-| **Claude Code** | `npx thumbgate init --agent claude-code` |
-| **Cursor** | `npx thumbgate init --agent cursor` |
-| **VS Code / Open VSX** | [plugins/vscode-extension/README.md](plugins/vscode-extension/README.md) |
-| **Antigravity-compatible** | [plugins/antigravity-extension/INSTALL.md](plugins/antigravity-extension/INSTALL.md) |
-| **JetBrains** | [plugins/jetbrains-plugin/README.md](plugins/jetbrains-plugin/README.md) |
-| **Codex** | `npx thumbgate init --agent codex` |
-| **Gemini CLI** | `npx thumbgate init --agent gemini` |
-| **Amp** | `npx thumbgate init --agent amp` |
-| **Cline** (Roo Code successor) | `npx thumbgate init --agent cline` |
-| **OpenCode** | `npx thumbgate init --agent opencode` |
-| **Claude Desktop** | [Download extension bundle](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-claude-desktop.mcpb) |
-| **Any MCP agent** | `npx thumbgate serve` |
-
-Works with **Claude Code, Cursor, Codex, Gemini CLI, Amp, Cline, OpenCode**, and any MCP-compatible agent. Migrating from Roo Code (sunsetting 2026-05-15)? See [`adapters/cline/INSTALL.md`](./adapters/cline/INSTALL.md).
+Enforcement depends on what the harness lets us intercept, so the table says which
+you get. This distinction is real: with a pre-tool hook ThumbGate stops the action
+before it runs; over MCP only, ThumbGate answers `gate_check` and the agent decides
+whether to obey.
+
+| Agent | Command | Enforcement |
+|-------|---------|-------------|
+| **Claude Code** | `npx thumbgate init --agent claude-code` | Hard — PreToolUse hook |
+| **Codex** | `npx thumbgate init --agent codex` | Hard — `pre_tool_use` hook |
+| **Gemini CLI** | `npx thumbgate init --agent gemini` | Hard — PreToolUse hook |
+| **ForgeCode** | `npx thumbgate init --agent forge` | Hard — `pre_tool_use` trigger |
+| **Cursor** | `npx thumbgate init --agent cursor` | Advisory — MCP `gate_check` |
+| **Cline** (Roo Code successor) | `npx thumbgate init --agent cline` | Advisory — MCP `gate_check` + `.clinerules` |
+| **OpenCode** | `npx thumbgate init --agent opencode` | Advisory — MCP `gate_check` |
+| **Any MCP agent** | `npx thumbgate serve` | Advisory — MCP `gate_check` |
+| **Amp** | `npx thumbgate init --agent amp` | Feedback capture only |
+| **Claude Desktop** | [Download extension bundle](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-claude-desktop.mcpb) | Advisory — MCP |
+| **VS Code / Open VSX** | [plugins/vscode-extension/README.md](plugins/vscode-extension/README.md) | See plugin README |
+| **Antigravity-compatible** | [plugins/antigravity-extension/INSTALL.md](plugins/antigravity-extension/INSTALL.md) | See plugin README |
+| **JetBrains** | [plugins/jetbrains-plugin/README.md](plugins/jetbrains-plugin/README.md) | See plugin README |
+
+**Advisory means the agent can ignore it.** Harnesses without a pre-tool hook expose no
+interception point, so ThumbGate cannot stop the call itself — it returns a verdict the
+agent is instructed to honor. Treat advisory coverage as a strong default, not a
+guarantee, and prefer a hard-enforcement harness for anything irreversible.
+
+The gate is **model-agnostic**: verdicts come from deterministic policy evaluation over
+the proposed tool call (`scripts/gates-engine.js`), never from an LLM. Swapping the model
+behind any harness does not change what is allowed.
+
+> **Enforcement posture:** ThumbGate ships **warn-by-default** — a matched gate is logged
+> and surfaced, not blocked. Set `THUMBGATE_STRICT_ENFORCEMENT=1` to hard-block. The
+> `gate_check` tool reports `warn` (never `allow`) when a gate matched but posture
+> downgraded it, so an agent is never told a flagged action is fine.
 
 ### Install scope: machine-wide vs per-project
 

package/adapters/claude/.mcp.json

@@ -2,13 +2,13 @@
   "mcpServers": {
     "thumbgate": {
       "command": "npx",
-      "args": ["--yes", "--package", "thumbgate@1.30.0", "thumbgate", "serve"]
+      "args": ["--yes", "--package", "thumbgate@1.31.0", "thumbgate", "serve"]
     }
   },
   "hooks": {
     "preToolUse": {
       "command": "npx",
-      "args": ["--yes", "--package", "thumbgate@1.30.0", "thumbgate", "gate-check"]
+      "args": ["--yes", "--package", "thumbgate@1.31.0", "thumbgate", "gate-check"]
     }
   }
 }

package/adapters/forge/forge.yaml

@@ -9,12 +9,12 @@ version: "1"
 skills:
   thumbgate-gate-check:
     description: "ThumbGate PreToolUse gate — blocks known-bad tool calls"
-    command: "npx --yes --package thumbgate@1.30.0 thumbgate gate-check"
+    command: "npx --yes --package thumbgate@1.31.0 thumbgate gate-check"
     trigger: pre_tool_use
 
   thumbgate-feedback:
     description: "ThumbGate feedback capture — logs user prompt context"
-    command: "npx --yes --package thumbgate@1.30.0 thumbgate hook-auto-capture"
+    command: "npx --yes --package thumbgate@1.31.0 thumbgate hook-auto-capture"
     trigger: user_prompt
 
 mcp:
@@ -23,6 +23,6 @@ mcp:
     args:
       - "--yes"
       - "--package"
-      - "thumbgate@1.30.0"
+      - "thumbgate@1.31.0"
       - "thumbgate"
       - "serve"

package/adapters/mcp/server-stdio.js

@@ -133,9 +133,7 @@ const {
     throw error;
   },
 }));
-const {
-  searchThumbgate,
-} = require('../../scripts/thumbgate-search');
+const { searchThumbgateAsync } = require('../../scripts/thumbgate-search');
 const {
   buildMultimodalRetrievalPlan,
 } = require('../../scripts/multimodal-retrieval-plan');
@@ -317,7 +315,7 @@ const {
   finalizeSession: finalizeFeedbackSession,
 } = require('../../scripts/feedback-session');
 
-const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.30.0' };
+const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.31.0' };
 const COMMERCE_CATEGORIES = [
   'product_recommendation',
   'brand_compliance',
@@ -971,14 +969,14 @@ async function callToolInner(name, args) {
       return buildSuggestFixResponse(args);
     case 'retrieve_lessons': {
       // Cross-encoder reranking: retrieve more candidates, then rerank for precision
-      const { retrieveWithRerankingSync } = loadOptionalModule(path.join(__dirname, '../../scripts/cross-encoder-reranker'), () => ({
-        retrieveWithRerankingSync: (toolName, actionContext, options = {}) => retrieveRelevantLessons(
+      const { retrieveWithReranking } = loadOptionalModule(path.join(__dirname, '../../scripts/cross-encoder-reranker'), () => ({
+        retrieveWithReranking: async (toolName, actionContext, options = {}) => retrieveRelevantLessons(
           toolName,
           actionContext,
           { maxResults: options.maxResults || 5 },
         ),
       }));
-      return toTextResult(retrieveWithRerankingSync(
+      return toTextResult(await retrieveWithReranking(
         args.toolName,
         args.actionContext || '',
         {
@@ -987,6 +985,9 @@ async function callToolInner(name, args) {
           scope: args.scope,
           requireScope: args.requireScope === true,
           includeShared: args.includeShared !== false,
+          metadataFilters: args.filters,
+          queryRewrite: args.queryRewrite !== false,
+          includeRetrievalMeta: args.includeRetrievalMeta === true,
         },
       ));
     }
@@ -1009,11 +1010,13 @@ async function callToolInner(name, args) {
     }
     case 'search_thumbgate':
       enforceLimit('search_thumbgate');
-      return toTextResult(searchThumbgate({
+      return toTextResult(await searchThumbgateAsync({
         query: args.query,
         limit: args.limit,
         source: args.source,
         signal: args.signal,
+        metadataFilters: args.filters,
+        queryRewrite: args.queryRewrite !== false,
       }));
     case 'import_document':
       return toTextResult(importDocument({
@@ -1038,6 +1041,61 @@ async function callToolInner(name, args) {
       }
       return toTextResult(document);
     }
+    case 'gate_check': {
+      // Same engine the PreToolUse hook uses, so an MCP client and a hook cannot
+      // disagree about whether an action is allowed.
+      const { runAsync } = require('../../scripts/gates-engine');
+      const { canonicalizeToolCall } = require('../../scripts/harness-tool-names');
+      const canonical = canonicalizeToolCall(args.tool_name, args.tool_input || {});
+      const raw = await runAsync({
+        tool_name: canonical.toolName,
+        tool_input: canonical.toolInput,
+      });
+      let decision = 'allow';
+      let reason = '';
+      let flagged = false;
+      try {
+        const parsed = JSON.parse(raw);
+        const hook = parsed.hookSpecificOutput || {};
+        const verdict = hook.permissionDecision || parsed.decision || '';
+        reason = hook.permissionDecisionReason || parsed.reason || hook.additionalContext || '';
+        // The hook wire format says "deny"; the documented tool contract says "block".
+        if (verdict === 'deny' || verdict === 'block') {
+          decision = 'block';
+          flagged = true;
+        } else if (/\[GATE:/.test(reason)) {
+          // A gate MATCHED but the warn-by-default posture downgraded it. Reporting
+          // "allow" here is how this tool would become theater: .clinerules tells the
+          // agent to abort only on "block", so a matched rm -rf / would have been run
+          // with the warning text ignored. "warn" is the honest third state.
+          decision = 'warn';
+          flagged = true;
+        }
+      } catch (_) {
+        // Unparseable engine output must never read as "allow" — fail closed.
+        decision = 'error';
+        reason = 'gate engine returned unparseable output';
+      }
+      const strict = process.env.THUMBGATE_STRICT_ENFORCEMENT === '1';
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            decision,
+            flagged,
+            enforcement: strict ? 'strict' : 'warn-by-default',
+            guidance: decision === 'block'
+              ? 'Do NOT run this action. Surface the reason to the user.'
+              : decision === 'warn'
+                ? 'A policy gate matched but enforcement is warn-by-default. Do NOT run this action without explicit user confirmation; show them the reason.'
+                : decision === 'error'
+                  ? 'Gate evaluation failed. Treat as unsafe and ask the user.'
+                  : 'No policy gate matched.',
+            reason,
+          }, null, 2),
+        }],
+      };
+    }
     case 'feedback_stats':
       return toTextResult(analyzeFeedback(undefined, { humanOnly: true }));
     case 'diagnose_failure':

package/adapters/opencode/opencode.json

@@ -7,7 +7,7 @@
         "npx",
         "--yes",
         "--package",
-        "thumbgate@1.30.0",
+        "thumbgate@1.31.0",
         "thumbgate",
         "serve"
       ],

package/bench/observability-eval-suite.json

@@ -4,7 +4,7 @@
       "id": "checkout-link-grounding",
       "traceId": "trace_checkout_001",
       "question": "Is the Pro checkout link working?",
-      "response": "The Pro checkout link is working because the checkout diagnostic confirms Stripe Pro checkout is reachable.",
+      "response": "The Pro checkout link is working because the checkout diagnostic confirms Stripe Pro checkout is reachable [context-1].",
       "retrievedContexts": [
         "Stripe Pro checkout diagnostic confirms the Pro checkout link is reachable and returns a valid checkout target.",
         "The workflow sprint checkout is intake-led and should not expose a stale payment link."
@@ -15,7 +15,7 @@
       "id": "letta-tool-gate",
       "traceId": "trace_letta_001",
       "question": "Should Letta execute a force push tool call?",
-      "response": "ThumbGate blocks force push before execution for Letta tool calls.",
+      "response": "ThumbGate blocks force push before execution for Letta tool calls [context-1].",
       "retrievedContexts": [
         "ThumbGate's Letta adapter wraps Letta tool calls and runs gate-check before the executor is called.",
         "Force push to main is a blocked high-risk git action."

package/bin/cli.js

@@ -39,7 +39,6 @@ const {
   codexAutoUpdateCliEntry,
   codexAutoUpdateMcpEntry,
   isSourceCheckout,
-  publishedCliAvailable,
   localMcpEntry,
   resolveMcpEntry,
 } = require(path.join(__dirname, '..', 'scripts', 'mcp-config'));
@@ -411,16 +410,17 @@ function canonicalMcpEntry(scope = 'project') {
 }
 
 function canonicalCodexMcpEntry() {
-  const version = pkgVersion();
-  if (isSourceCheckout(PKG_ROOT) && !publishedCliAvailable(version)) {
+  // Codex config is user-global and must survive disposable worktree cleanup.
+  // Use the stable published launcher even when init is invoked from source;
+  // developers can explicitly opt into a checkout-pinned runtime when needed.
+  if (isSourceCheckout(PKG_ROOT) && process.env.THUMBGATE_CODEX_USE_SOURCE_RUNTIME === '1') {
     return localMcpEntry(PKG_ROOT, 'home');
   }
   return codexAutoUpdateMcpEntry();
 }
 
 function canonicalCodexCliEntry(commandArgs) {
-  const version = pkgVersion();
-  if (isSourceCheckout(PKG_ROOT) && !publishedCliAvailable(version)) {
+  if (isSourceCheckout(PKG_ROOT) && process.env.THUMBGATE_CODEX_USE_SOURCE_RUNTIME === '1') {
     return {
       command: 'node',
       args: [path.join(PKG_ROOT, 'bin', 'cli.js'), ...commandArgs],
@@ -584,7 +584,20 @@ function detectPlatform(name, checks) {
 }
 
 function whichExists(cmd) {
-  try { execSync(`which ${cmd}`, { stdio: 'pipe' }); return true; } catch (_) { return false; }
+  if (!cmd || /[\\/]/.test(cmd)) return false;
+  const pathEntries = String(process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const extensions = process.platform === 'win32'
+    ? String(process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';')
+    : [''];
+  return pathEntries.some((entry) => extensions.some((extension) => {
+    const candidate = path.join(entry, `${cmd}${extension}`);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return fs.statSync(candidate).isFile();
+    } catch (_) {
+      return false;
+    }
+  }));
 }
 
 function setupClaude() {
@@ -636,18 +649,26 @@ function setupCodex() {
   return configChanged || hookResult.changed;
 }
 
-function setupGemini() {
-  // Try to import custom commands as a Gemini plugin if the CLI is installed
-  const { execSync } = require('child_process');
+function setupGemini(options = {}) {
+  // Importing a plugin executes an external package manager and can mutate
+  // machine-wide Gemini state. Keep ordinary init/quick-start deterministic;
+  // operators can opt in explicitly when they want the plugin import too.
+  const importPlugin = options.importPlugin === true
+    || process.env.THUMBGATE_IMPORT_AGENT_PLUGINS === '1';
   let pluginImported = false;
-  for (const binName of ['agy', 'gemini']) {
-    try {
-      execSync(`${binName} plugin import "${PKG_ROOT}" --force`, { stdio: 'ignore' });
-      console.log(`  Gemini: imported thumbgate plugin via ${binName}`);
-      pluginImported = true;
-      break;
-    } catch (err) {
-      // ignore errors if command doesn't exist or fails
+  if (importPlugin) {
+    for (const binName of ['agy', 'gemini']) {
+      try {
+        execFileSync(binName, ['plugin', 'import', PKG_ROOT, '--force'], {
+          stdio: 'ignore',
+          timeout: 5000,
+        });
+        console.log(`  Gemini: imported thumbgate plugin via ${binName}`);
+        pluginImported = true;
+        break;
+      } catch (err) {
+        // A missing, failing, or slow optional plugin manager must not block init.
+      }
     }
   }
 
@@ -693,6 +714,66 @@ function setupAmp() {
   return true;
 }
 
+function setupOpenCode() {
+  // OpenCode was listed in README's install table and in `init --help` since the
+  // adapter asset landed, but no setup function ever existed — `--agent opencode`
+  // silently wrote Claude/Codex/Gemini config and exited 0. OpenCode has no hook
+  // surface, so this wires the MCP server, which is its real integration point.
+  const configPath = path.join(HOME, '.config', 'opencode', 'opencode.json');
+  const srcPath = path.join(PKG_ROOT, 'adapters', 'opencode', 'opencode.json');
+  if (!fs.existsSync(srcPath)) return false;
+
+  let src;
+  try { src = JSON.parse(fs.readFileSync(srcPath, 'utf8')); } catch (_) { return false; }
+  const desired = (src.mcp || {}).thumbgate;
+  if (!desired) return false;
+
+  let config = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (error) {
+      // Resetting to {} here and writing would replace the whole file — silently deleting
+      // the user's model, provider, plugin and other MCP settings just to add ours.
+      // A config we cannot parse is a reason to stop, not to overwrite.
+      console.error(`  OpenCode: ${configPath} could not be parsed (${error.message}).`);
+      console.error('  Refusing to overwrite it. Fix or move the file, then re-run.');
+      process.exitCode = 1;
+      return false;
+    }
+  }
+  config.mcp = config.mcp || {};
+  if (JSON.stringify(config.mcp[MCP_SERVER_NAME]) === JSON.stringify(desired)) return false;
+
+  config.$schema = config.$schema || src.$schema;
+  config.mcp[MCP_SERVER_NAME] = desired;
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  console.log(`  OpenCode: registered thumbgate MCP server in ${configPath}`);
+  return true;
+}
+
+// Single source of truth for `--agent`. Every value advertised in `init --help`
+// and README.md must appear here with a real handler, or the flag lies.
+// `hookAgent: true` means scripts/auto-wire-hooks.js can wire a pre-tool hook;
+// the rest integrate over MCP only and are wired by their setup function.
+const AGENT_ALIASES = {
+  claude: 'claude-code',
+  'claude_code': 'claude-code',
+  'open-code': 'opencode',
+};
+
+const SUPPORTED_AGENTS = {
+  'claude-code': { hookAgent: true },
+  codex: { hookAgent: true },
+  gemini: { hookAgent: true },
+  forge: { hookAgent: true },
+  cursor: { hookAgent: true },
+  cline: { hookAgent: false, setup: () => setupCline() },
+  amp: { hookAgent: false, setup: () => setupAmp() },
+  opencode: { hookAgent: false, setup: () => setupOpenCode() },
+};
+
 function setupCursor() {
   return mergeMcpJson(path.join(CWD, '.cursor', 'mcp.json'), 'Cursor', 'project');
 }
@@ -934,14 +1015,23 @@ function quickstart() {
 
 function init(cliArgs = parseArgs(process.argv.slice(3))) {
   const args = { ...cliArgs };
+  // A typo used to exit 0 having wired nothing for the requested agent.
+  // Aliases must resolve BEFORE validation: scripts/auto-wire-hooks.js accepts `claude`
+  // for `claude-code`, and plugins/claude-skill/README.md publishes that exact command.
+  if (args.agent && AGENT_ALIASES[args.agent]) args.agent = AGENT_ALIASES[args.agent];
+  if (args.agent && !Object.prototype.hasOwnProperty.call(SUPPORTED_AGENTS, args.agent)) {
+    console.error(`Unknown --agent "${args.agent}". Supported: ${Object.keys(SUPPORTED_AGENTS).join(', ')}`);
+    process.exit(1);
+  }
   if (args.help || args.h) {
-    console.log('Usage: npx thumbgate init [--agent <name>] [--wire-hooks] [--email you@company.com]');
+    console.log('Usage: npx thumbgate init [--agent <name>] [--wire-hooks] [--import-agent-plugins] [--email you@company.com]');
     console.log('');
     console.log('Scaffold ThumbGate in the current project and wire detected agent integrations.');
     console.log('');
     console.log('Options:');
-    console.log('  --agent <name>           Wire a specific agent: claude-code, codex, gemini, amp, cursor, cline, opencode');
+    console.log(`  --agent <name>           Wire a specific agent: ${Object.keys(SUPPORTED_AGENTS).join(', ')}`);
     console.log('  --wire-hooks             Wire hooks only; do not scaffold project files');
+    console.log('  --import-agent-plugins   Also import optional agent plugins when supported');
     console.log('  --email <email>          Subscribe installer to the setup guide and trial reminders');
     console.log('  --dry-run                Show hook changes without writing them');
     return;
@@ -1037,17 +1127,26 @@ function init(cliArgs = parseArgs(process.argv.slice(3))) {
   let configured = 0;
 
   const platforms = [
-    { name: 'Claude Code', detect: [
+    { agent: 'claude-code', name: 'Claude Code', detect: [
       () => whichExists('claude'),
       () => fs.existsSync(path.join(HOME, '.claude')),
       () => fs.existsSync(path.join(CWD, '.claude')),
     ], setup: setupClaude },
-    { name: 'Codex', detect: [() => whichExists('codex'), () => fs.existsSync(path.join(HOME, '.codex'))], setup: setupCodex },
-    { name: 'Gemini', detect: [() => whichExists('gemini'), () => fs.existsSync(path.join(HOME, '.gemini'))], setup: setupGemini },
-    { name: 'Amp', detect: [() => whichExists('amp'), () => fs.existsSync(path.join(HOME, '.amp'))], setup: setupAmp },
-    { name: 'Cursor', detect: [() => fs.existsSync(path.join(HOME, '.cursor', 'mcp.json')), () => fs.existsSync(path.join(CWD, '.cursor'))], setup: setupCursor },
-    { name: 'ForgeCode', detect: [() => whichExists('forge'), () => fs.existsSync(path.join(CWD, 'forge.yaml'))], setup: setupForge },
-    { name: 'Cline', detect: [
+    { agent: 'codex', name: 'Codex', detect: [() => whichExists('codex'), () => fs.existsSync(path.join(HOME, '.codex'))], setup: setupCodex },
+    {
+      agent: 'gemini',
+      name: 'Gemini',
+      detect: [
+        () => whichExists('gemini'),
+        () => whichExists('agy'),
+        () => fs.existsSync(path.join(HOME, '.gemini')),
+      ],
+      setup: () => setupGemini({ importPlugin: args['import-agent-plugins'] === true }),
+    },
+    { agent: 'amp', name: 'Amp', detect: [() => whichExists('amp'), () => fs.existsSync(path.join(HOME, '.amp'))], setup: setupAmp },
+    { agent: 'cursor', name: 'Cursor', detect: [() => fs.existsSync(path.join(HOME, '.cursor', 'mcp.json')), () => fs.existsSync(path.join(CWD, '.cursor'))], setup: setupCursor },
+    { agent: 'forge', name: 'ForgeCode', detect: [() => whichExists('forge'), () => fs.existsSync(path.join(CWD, 'forge.yaml'))], setup: setupForge },
+    { agent: 'cline', name: 'Cline', detect: [
       () => fs.existsSync(path.join(CWD, '.clinerules')),
       () => process.platform === 'darwin' && fs.existsSync(path.join(HOME, 'Library', 'Application Support', 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev')),
       () => process.platform === 'linux' && fs.existsSync(path.join(HOME, '.config', 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev')),
@@ -1056,6 +1155,11 @@ function init(cliArgs = parseArgs(process.argv.slice(3))) {
   ];
 
   for (const p of platforms) {
+    // An explicit target must stay scoped to that integration. Quick-start
+    // always resolves one target before calling init; configuring every other
+    // CLI merely because it exists on PATH caused surprise machine mutations
+    // and multi-second hangs in ordinary onboarding.
+    if (args.agent && p.agent !== args.agent) continue;
     if (detectPlatform(p.name, p.detect)) {
       const didSetup = p.setup();
       if (didSetup) configured++;
@@ -1076,15 +1180,27 @@ function init(cliArgs = parseArgs(process.argv.slice(3))) {
 
   if (configured === 0) console.log('  All detected platforms already configured.');
 
-  // Cline uses .clinerules (no native hook surface). Run setupCline directly
-  // and skip wireHooks, which does not support cline.
-  if (args.agent === 'cline') {
-    setupCline();
+  // Agents without a native pre-tool hook surface (cline, amp, opencode) are wired
+  // by their own setup function. Previously only cline was handled here: `--agent amp`
+  // and `--agent opencode` fell through to wireHooks, which rejected them, printed the
+  // rejection as an ordinary log line, and exited 0 — so the flag appeared to work
+  // while writing nothing for that agent.
+  const agentSpec = args.agent ? SUPPORTED_AGENTS[args.agent] : null;
+  if (agentSpec && agentSpec.setup) {
+    // A setup function returns false both when nothing needed doing and when it refused
+    // (e.g. an unparseable config it declined to overwrite). Reporting "already
+    // configured" for a refusal would repeat the original sin of this PR: a failure
+    // dressed up as success. The refusal path sets process.exitCode, so key off that.
+    const changed = agentSpec.setup();
+    if (!changed && !process.exitCode) console.log(`  ${args.agent}: already configured`);
   } else if (args.agent || args['wire-hooks']) {
     const { wireHooks } = require(path.join(PKG_ROOT, 'scripts', 'auto-wire-hooks'));
     const hookResult = wireHooks({ agent: args.agent, dryRun: args['dry-run'] });
     if (hookResult.error) {
-      console.log(`  Hook wiring: ${hookResult.error}`);
+      // An explicit --agent that cannot be wired is a FAILURE, not a note. Exiting 0
+      // here is what let a user believe `--agent opencode` had protected them.
+      console.error(`  Hook wiring failed for --agent ${args.agent}: ${hookResult.error}`);
+      process.exitCode = 1;
     } else if (!hookResult.changed) {
       console.log(`  Hooks: already wired for ${hookResult.agent}`);
     } else {