thumbgate 1.30.0 → 1.34.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.34.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.34.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.34.0", "thumbgate", "serve"]
     }
   },
   "hooks": {
     "preToolUse": {
       "command": "npx",
-      "args": ["--yes", "--package", "thumbgate@1.30.0", "thumbgate", "gate-check"]
+      "args": ["--yes", "--package", "thumbgate@1.34.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.34.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.34.0 thumbgate hook-auto-capture"
     trigger: user_prompt
 
 mcp:
@@ -23,6 +23,6 @@ mcp:
     args:
       - "--yes"
       - "--package"
-      - "thumbgate@1.30.0"
+      - "thumbgate@1.34.0"
       - "thumbgate"
       - "serve"

package/adapters/mcp/server-stdio.js

@@ -95,6 +95,19 @@ const {
   listEscalations,
   requestEscalation,
 } = require('../../scripts/human-escalation');
+const {
+  createPurchaseRequisition,
+  getFinancialControlRuntimeOptions,
+  getRuntimePrincipal,
+  listPurchaseRequisitions,
+  reconcilePurchaseLedger,
+  reservePurchaseRequisition,
+  settlePurchaseRequisition,
+} = require('../../scripts/financial-control-plane');
+const MCP_FINANCIAL_PRINCIPAL = getRuntimePrincipal();
+const MCP_FINANCIAL_OPTIONS = getFinancialControlRuntimeOptions({
+  authenticatedPrincipal: MCP_FINANCIAL_PRINCIPAL,
+});
 const { recordReasoningTrace } = require('../../scripts/agent-reasoning-traces');
 const { recordToolCall } = require('../../scripts/tool-kpi-tracker');
 const {
@@ -133,9 +146,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 +328,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.34.0' };
 const COMMERCE_CATEGORIES = [
   'product_recommendation',
   'brand_compliance',
@@ -971,14 +982,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 +998,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 +1023,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 +1054,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':
@@ -1310,6 +1381,20 @@ async function callToolInner(name, args) {
       return toTextResult(requestEscalation(args));
     case 'list_human_escalations':
       return toTextResult(listEscalations({ status: args.status }).slice(0, Number(args.limit || 20)));
+    case 'create_purchase_requisition':
+      return toTextResult(createPurchaseRequisition(args, MCP_FINANCIAL_OPTIONS));
+    case 'list_purchase_requisitions': {
+      const rows = listPurchaseRequisitions(MCP_FINANCIAL_OPTIONS)
+        .filter((entry) => !args.status || entry.status === args.status)
+        .slice(0, Number(args.limit || 20));
+      return toTextResult(rows);
+    }
+    case 'reserve_purchase_requisition':
+      return toTextResult(reservePurchaseRequisition(args, MCP_FINANCIAL_OPTIONS));
+    case 'settle_purchase_requisition':
+      return toTextResult(settlePurchaseRequisition(args, MCP_FINANCIAL_OPTIONS));
+    case 'reconcile_purchase_ledger':
+      return toTextResult(reconcilePurchaseLedger(MCP_FINANCIAL_OPTIONS));
     case 'verify_claim':
       return toTextResult(verifyClaimEvidence(args.claim, { goalContract: args.goalContract }));
     case 'require_evidence_for_claim': {
@@ -1324,6 +1409,9 @@ async function callToolInner(name, args) {
       const missingActions = hasMatchingChecks
         ? Array.from(new Set(verification.checks.flatMap((check) => check.missing || [])))
         : [];
+      const factualMismatches = Array.isArray(verification.universal && verification.universal.checks)
+        ? verification.universal.checks.filter((check) => !check.passed)
+        : [];
       try {
         const { recordAuditEvent } = require('../../scripts/audit-trail');
         recordAuditEvent({
@@ -1335,13 +1423,16 @@ async function callToolInner(name, args) {
             goalContract: verification.goalContract && verification.goalContract.matched
               ? verification.goalContract
               : null,
+            universalParsed: verification.universal ? verification.universal.parsedCount : 0,
           },
           decision: blocking ? 'deny' : 'allow',
           gateId: verification.goalContract && verification.goalContract.matched
             ? 'completion_goal_contract'
-            : 'completion_claim',
+            : (factualMismatches.length > 0 ? 'completion_claim_factual' : 'completion_claim'),
           message: blocking
-            ? `Completion claim blocked — missing evidence: ${missingActions.join(', ') || 'unknown'}`
+            ? (factualMismatches.length > 0
+              ? `Completion claim blocked — factual mismatch/unconfigured: ${factualMismatches.map((c) => c.message).join('; ')}`
+              : `Completion claim blocked — missing evidence: ${missingActions.join(', ') || 'unknown'}`)
             : `Completion claim verified (${verification.verified ? 'evidence present' : 'no matching gate'})`,
           source: 'completion-gate',
         });
@@ -1355,6 +1446,8 @@ async function callToolInner(name, args) {
         missingActions,
         checks: verification.checks,
         goalContract: verification.goalContract,
+        universal: verification.universal,
+        factualMismatches,
         sessionId: args.sessionId || null,
       });
     }
@@ -1419,6 +1512,7 @@ async function callToolInner(name, args) {
         mcp: args.mcp,
         mcpToolCall: args.mcpToolCall,
         budget: args.budget,
+        financialControl: args.financialControl,
         usage: args.usage,
       }, {
         provider: args.provider,
@@ -1428,6 +1522,7 @@ async function callToolInner(name, args) {
         tokenEstimate: args.tokenEstimate,
         costUsd: args.costUsd,
         budget: args.budget,
+        financialControl: args.financialControl,
         repoPath: args.repoPath,
         baseBranch: args.baseBranch,
         affectedFiles: changedFiles.length > 0 ? changedFiles : undefined,

package/adapters/opencode/opencode.json

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