thumbgate 1.29.2 → 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.29.2",
+  "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.29.2",
+  "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.29.2", "thumbgate", "serve"]
+      "args": ["--yes", "--package", "thumbgate@1.31.0", "thumbgate", "serve"]
     }
   },
   "hooks": {
     "preToolUse": {
       "command": "npx",
-      "args": ["--yes", "--package", "thumbgate@1.29.2", "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.29.2 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.29.2 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.29.2"
+      - "thumbgate@1.31.0"
       - "thumbgate"
       - "serve"

package/adapters/mcp/server-stdio.js

@@ -96,6 +96,7 @@ const {
   requestEscalation,
 } = require('../../scripts/human-escalation');
 const { recordReasoningTrace } = require('../../scripts/agent-reasoning-traces');
+const { recordToolCall } = require('../../scripts/tool-kpi-tracker');
 const {
   evaluateOperationalIntegrity,
 } = require('../../scripts/operational-integrity');
@@ -132,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');
@@ -316,7 +315,7 @@ const {
   finalizeSession: finalizeFeedbackSession,
 } = require('../../scripts/feedback-session');
 
-const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.29.2' };
+const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.31.0' };
 const COMMERCE_CATEGORIES = [
   'product_recommendation',
   'brand_compliance',
@@ -379,6 +378,9 @@ function toTextResult(payload) {
   const text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
   return {
     content: [{ type: 'text', text }],
+    ...(payload !== null && typeof payload === 'object'
+      ? { structuredContent: payload }
+      : {}),
   };
 }
 
@@ -416,7 +418,7 @@ function toCaptureFeedbackTextResult(result) {
   if (reminder) {
     blocks.push({ type: 'text', text: reminder });
   }
-  return { content: blocks };
+  return { content: blocks, structuredContent: result };
 }
 
 function formatContextPack(pack) {
@@ -758,10 +760,27 @@ function buildEstimateUncertaintyResponse(args = {}) {
 }
 
 async function callTool(name, args = {}) {
+  const attemptStartMs = Date.now();
   const activeProfile = getActiveMcpProfile();
-  assertToolAllowed(name, activeProfile);
+  try {
+    assertToolAllowed(name, activeProfile);
+  } catch (error) {
+    recordMcpToolTrace(name, args, {
+      success: false,
+      category: 'profile_denied',
+      evidence: [error.message],
+      latencyMs: Date.now() - attemptStartMs,
+    });
+    throw error;
+  }
   const capability = getToolCapability(name);
   if (!capability.available) {
+    recordMcpToolTrace(name, args, {
+      success: false,
+      category: 'capability',
+      evidence: capability.missingModules,
+      latencyMs: Date.now() - attemptStartMs,
+    });
     if (capability.availability === 'private_core') {
       return unavailablePrivateMcpFeature(name);
     }
@@ -788,6 +807,7 @@ async function callTool(name, args = {}) {
         success: false,
         category: 'contract',
         evidence: validation.errors,
+        latencyMs: Date.now() - attemptStartMs,
       });
       throw err;
     }
@@ -803,6 +823,7 @@ async function callTool(name, args = {}) {
         success: false,
         category: 'permission',
         evidence: [firewallResult.message],
+        latencyMs: Date.now() - attemptStartMs,
       });
       throw err;
     }
@@ -816,11 +837,24 @@ async function callTool(name, args = {}) {
       success: false,
       category: err.errorCategory || 'execution',
       evidence: [err.code || err.message || 'tool execution failed'],
-      latencyMs: Date.now() - startMs,
+      latencyMs: Date.now() - attemptStartMs,
     });
     throw err;
   }
   const latencyMs = Date.now() - startMs;
+  const outputValidation = validateMcpToolOutput(toolDef, result);
+  if (!outputValidation.valid) {
+    const err = new Error(`Structured output contract violation on '${name}': ${outputValidation.errors.join('; ')}`);
+    err.errorCategory = 'output_contract';
+    err.isRetryable = false;
+    recordMcpToolTrace(name, args, {
+      success: false,
+      category: 'output_contract',
+      evidence: outputValidation.errors,
+      latencyMs,
+    });
+    throw err;
+  }
   recordMcpToolTrace(name, args, {
     success: true,
     category: 'success',
@@ -840,7 +874,31 @@ async function callTool(name, args = {}) {
   return result;
 }
 
+function validateMcpToolOutput(toolDef, result) {
+  if (!toolDef || !toolDef.outputSchema) return { valid: true, errors: [] };
+  const { validateStructuredOutput } = require('../../scripts/tool-contract-validator');
+  if (!result || result.structuredContent === undefined) {
+    return { valid: false, errors: ['Tool response is missing structuredContent'] };
+  }
+  return validateStructuredOutput(result.structuredContent, toolDef.outputSchema);
+}
+
 function recordMcpToolTrace(name, args, outcome = {}) {
+  try {
+    recordToolCall({
+      toolName: name,
+      serverName: 'mcp',
+      latencyMs: Number(outcome.latencyMs || 0),
+      success: outcome.success === true,
+      agentId: args.agentId || args.processId || args.taskId || 'unknown',
+      metadata: {
+        category: outcome.category || 'unknown',
+        traceId: args.traceId || args.taskId || null,
+      },
+    });
+  } catch {
+    // KPI telemetry must not change the tool's functional outcome.
+  }
   try {
     const traceId = args.traceId || args.taskId || `mcp-${Date.now()}-${name}`;
     recordReasoningTrace({
@@ -888,10 +946,13 @@ async function callToolInner(name, args) {
       // action receipt (this action -> this outcome) before promotion. Returns
       // args unchanged when there is no matching receipt (non-breaking).
       const pairedFeedback = pairFeedbackWithReceipt(args);
-      return toCaptureFeedbackTextResult(captureFeedback(pairedFeedback));
+      return toCaptureFeedbackTextResult(captureFeedback({
+        ...pairedFeedback,
+        reviewOrigin: 'automated',
+      }));
     }
     case 'feedback_summary':
-      return toTextResult(feedbackSummary(Number(args.recent || 20)));
+      return toTextResult(feedbackSummary(Number(args.recent || 20), { humanOnly: true }));
     case 'search_lessons': {
       const module = loadPrivateMcpModule('lessonSearch');
       if (!module) return unavailablePrivateMcpFeature('search_lessons');
@@ -899,25 +960,34 @@ async function callToolInner(name, args) {
         limit: Number(args.limit || 10),
         category: args.category,
         tags: Array.isArray(args.tags) ? args.tags : [],
+        scope: args.scope,
+        requireScope: args.requireScope === true,
+        includeShared: args.includeShared !== false,
       }));
     }
     case 'suggest_fix':
       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 || '',
         {
           candidateCount: 20,
           maxResults: Number(args.maxResults || 5),
+          scope: args.scope,
+          requireScope: args.requireScope === true,
+          includeShared: args.includeShared !== false,
+          metadataFilters: args.filters,
+          queryRewrite: args.queryRewrite !== false,
+          includeRetrievalMeta: args.includeRetrievalMeta === true,
         },
       ));
     }
@@ -940,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({
@@ -969,8 +1041,63 @@ 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());
+      return toTextResult(analyzeFeedback(undefined, { humanOnly: true }));
     case 'diagnose_failure':
       return buildDiagnoseFailureResponse(args);
     case 'reflect_on_feedback':
@@ -1148,6 +1275,7 @@ async function callToolInner(name, args) {
           workflowContract: args.workflowContract,
           repoPath: args.repoPath,
           localOnly: args.localOnly === true,
+          ttlMs: args.ttlMs,
           clear: args.clear === true,
         }),
       });
@@ -1744,5 +1872,6 @@ module.exports = {
     listAvailableTools,
     unavailablePrivateMcpFeature,
     callToolInner,
+    validateMcpToolOutput,
   },
 };

package/adapters/opencode/opencode.json

@@ -7,7 +7,7 @@
         "npx",
         "--yes",
         "--package",
-        "thumbgate@1.29.2",
+        "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."