thumbgate 1.27.19 → 1.27.20

package/.claude/commands/dashboard.md

@@ -0,0 +1,15 @@
+---
+name: dashboard
+description: Open the local HTTP dashboard for the current project in your web browser.
+---
+
+# Open Dashboard
+
+Open the local HTTP dashboard for the current project in your web browser.
+
+## Instructions
+Execute the following command in the project directory to open the browser dashboard scoped to the current repository:
+```bash
+thumbgate-dashboard
+```
+

package/.claude/commands/thumbgate-blocked.md

@@ -0,0 +1,27 @@
+---
+name: thumbgate-blocked
+description: Show what ThumbGate has actually blocked — gate enforcement stats and the full enforcement matrix. Use for "what has ThumbGate blocked", "show gate stats", "is enforcement working", "how many tokens did we save", "enforcement matrix".
+allowed-tools: mcp__thumbgate__gate_stats, mcp__thumbgate__enforcement_matrix, Bash(npx thumbgate gate-stats:*)
+---
+
+# ThumbGate Blocked
+
+Show the enforcement record: how many risky actions were blocked vs warned, which gates fire most, and the full feedback → check → rejection pipeline.
+
+This command wraps existing ThumbGate capability — **no new logic**. It reads the live enforcement counters.
+
+## Steps
+
+1. Call the `gate_stats` MCP tool for the headline numbers: blocked count, warned count, and the top gates by hits. (CLI fallback: `npx thumbgate gate-stats`.)
+2. Call the `enforcement_matrix` MCP tool for the full picture: feedback pipeline stats, active pre-action checks, and the rejection ledger with revival conditions.
+3. Summarize for the user:
+   - Total blocks (each block = a repeat mistake stopped before it spent tokens or did damage).
+   - Most-triggered gates.
+   - Anything in the rejection ledger that is close to revival.
+4. If counts are all zero, note that enforcement is wired but hasn't fired yet, and point to `/thumbgate-guard` to promote a rule.
+
+## Example
+
+```
+/thumbgate-blocked
+```

package/.claude/commands/thumbgate-dashboard.md

@@ -0,0 +1,15 @@
+---
+name: thumbgate-dashboard
+description: Open the local HTTP dashboard for the current project in your web browser.
+---
+
+# Open Scoped ThumbGate Dashboard
+
+Open the local HTTP dashboard for the current project in your web browser.
+
+## Instructions
+Execute the following command in the project directory to open the browser dashboard:
+```bash
+thumbgate-dashboard
+```
+

package/.claude/commands/thumbgate-doctor.md

@@ -0,0 +1,30 @@
+---
+name: thumbgate-doctor
+description: Health-check the ThumbGate wiring for this project — hooks, MCP server, and agent-readiness — and report what's broken. Use for "is ThumbGate wired up", "thumbgate doctor", "check my guardrails are installed", "why aren't my gates firing", "agent readiness".
+allowed-tools: Bash(npx thumbgate doctor:*), mcp__thumbgate__check_operational_integrity
+---
+
+# ThumbGate Doctor
+
+Audit whether ThumbGate is actually wired into this agent: PreToolUse / SessionStart hooks installed, MCP server reachable, lesson store present, and overall agent-readiness — then tell the user exactly what to fix.
+
+This command wraps existing ThumbGate capability — **no new logic**. It runs the existing doctor + integrity checks.
+
+## Steps
+
+1. Run the existing wiring/health audit:
+   ```bash
+   npx thumbgate doctor
+   ```
+   (Add `--json` for a machine-readable report.) It exits non-zero when the project is not `ready`.
+2. For deeper runtime state, call the `check_operational_integrity` MCP tool to verify the server-side enforcement path is live, not just the local config.
+3. Summarize:
+   - ✅ what's wired (hooks, MCP, store, statusline).
+   - ❌ what's missing, with the exact fix command (usually `npx thumbgate init`).
+4. If everything is green, say so plainly with the readiness status; if not, lead with the single highest-impact fix.
+
+## Example
+
+```
+/thumbgate-doctor
+```

package/.claude/commands/thumbgate-guard.md

@@ -0,0 +1,36 @@
+---
+name: thumbgate-guard
+description: Turn the last agent mistake into a hard prevention rule the agent cannot bypass. Use after a bad tool call, a wrong action, or a thumbs-down — "guard against this", "block this from happening again", "never do that again", "promote this to a rule".
+allowed-tools: mcp__thumbgate__capture_feedback, Bash(npx thumbgate force-gate:*), Bash(npx thumbgate quickstart:*)
+---
+
+# ThumbGate Guard
+
+Capture the mistake the agent just made and promote it into a Pre-Action Check (a `block` gate) so the same tool-call shape is intercepted before it runs again — in this and every future session, across Claude Code, Cursor, Codex, Gemini, Amp, and Cline.
+
+This command wraps existing ThumbGate capability. It adds **no new logic** — it routes to the real capture + force-promote path.
+
+## Steps
+
+1. Identify the specific bad action from the recent conversation (e.g. `git push --force origin main`, `DROP TABLE users`, deploy without tests). State it in one sentence.
+2. Record the signal with the `capture_feedback` MCP tool:
+   - `signal: "down"`
+   - `context`: one sentence describing what went wrong
+   - `whatWentWrong`: the concrete failure
+   - `whatToChange`: the prevention action
+   - `tags`: the domain (e.g. `git`, `database`, `deploy`)
+   - If the user only gave a vague signal, pass the recent turns through `conversationWindow` / `chatHistory` for history-aware distillation instead of refusing.
+3. Promote it to an enforced block gate using the existing force-promote path:
+   ```bash
+   npx thumbgate force-gate "<one-sentence context of the mistake>"
+   ```
+   This prints the new `gateId` and the total active gate count.
+4. Show the user the promoted rule and confirm it is now enforced as a PreToolUse block.
+
+> First rule of the project and want the guided walkthrough (capture → promote → watch it block once)? Run `npx thumbgate quickstart` instead.
+
+## Example
+
+```
+/thumbgate-guard the agent force-pushed to main and overwrote a teammate's commit
+```

package/.claude/commands/thumbgate-protect.md

@@ -0,0 +1,30 @@
+---
+name: thumbgate-protect
+description: Show this repo's branch/release governance and grant a scoped, time-limited approval for an action that touches protected files. Use for "protect this branch", "is main protected", "approve this protected change", "branch governance", "let me edit a protected file".
+allowed-tools: mcp__thumbgate__get_branch_governance, mcp__thumbgate__approve_protected_action
+---
+
+# ThumbGate Protect
+
+Inspect the protected-action posture for this project and, when the user explicitly approves, grant a scoped, expiring exception so a protected-file edit or publish can proceed under audit.
+
+This command wraps existing ThumbGate capability — **no new logic**. It reads governance state and records a time-boxed approval.
+
+## Steps
+
+1. Read the current posture with the `get_branch_governance` MCP tool: which branches are protected, release rules, and the protected-file globs in effect.
+2. Report it plainly: what is protected, and what the agent is currently blocked from touching without approval.
+3. **Only if the user explicitly asks to proceed**, grant a scoped approval with `approve_protected_action`:
+   - `pathGlobs`: the smallest set of protected globs the action needs.
+   - `reason`: why this is approved (one sentence).
+   - `evidence`: supporting note (tests passing, owner sign-off, etc.) when available.
+   - `ttlMs`: keep it short — default is 1 hour, never exceed what the task needs.
+4. Confirm the approval id, covered globs, and expiry. Approvals are deliberately temporary and audited; re-run for the next task.
+
+> This is for granting *narrow, temporary* exceptions, not for disabling protection. Never use it to bypass branch governance wholesale.
+
+## Example
+
+```
+/thumbgate-protect
+```

package/.claude/commands/thumbgate-rules.md

@@ -0,0 +1,30 @@
+---
+name: thumbgate-rules
+description: List the active prevention rules and learned lessons guarding this project. Use to answer "what is ThumbGate protecting me from", "show my gates/rules", "what has the agent learned", "what's blocked here".
+allowed-tools: mcp__thumbgate__prevention_rules, mcp__thumbgate__get_reliability_rules, mcp__thumbgate__search_lessons, Bash(npx thumbgate rules:*)
+---
+
+# ThumbGate Rules
+
+Show the guardrails currently in force for this project: the auto-promoted prevention rules, the reliability rules, and the promoted lessons behind them.
+
+This command wraps existing ThumbGate capability — **no new logic**. It reads the live rule + lesson stores.
+
+## Steps
+
+1. List the active prevention rules with the `prevention_rules` MCP tool (or the CLI fallback `npx thumbgate rules`).
+2. Pull the reliability rules with `get_reliability_rules` to show which tool-call shapes are gated.
+3. For each rule, surface the lesson it came from with `search_lessons` so the user sees *why* the rule exists, not just *what* it blocks.
+4. Present a compact table:
+
+   | Rule / Gate | Blocks | From lesson | State |
+   |-------------|--------|-------------|-------|
+   | … | … | … | active / archived |
+
+5. If there are zero active rules, point the user to `/thumbgate-guard` to promote their first one.
+
+## Example
+
+```
+/thumbgate-rules
+```

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.27.15",
+  "version": "1.27.20",
   "author": {
     "name": "Igor Ganapolsky",
     "email": "ig5973700@gmail.com",

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

@@ -1,6 +1,6 @@
 {
   "name": "thumbgate",
-  "version": "1.27.15",
+  "version": "1.27.20",
   "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

@@ -6,9 +6,6 @@
   </a>
 </p>
 
-> **⚡ LAUNCH PROMO: 50% off Pro for 3 months — use code `THUMB50`**
-> [$9.50/mo instead of $19 →](https://buy.stripe.com/eVqeVd62o0aO19v7mb3sI3g) · Limited to first 50 customers
-
 **AI coding agents repeat mistakes — and one wrong tool call can wipe a directory, leak a key, or push broken code.**
 
 ThumbGate is the local-first firewall for AI coding agents. It runs in the PreToolUse hook on your machine and blocks dangerous tool calls — `rm -rf`, secret exfiltration, off-scope edits, a bad `git push` — before they execute, across Claude Code, Cursor, Codex, Gemini, Amp, Cline, and OpenCode. No server, no gateway. (Regulated-industry policy templates — legal intake, financial compliance, healthcare — build on the same engine.)

package/adapters/claude/.mcp.json

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

package/adapters/gcp/dfcx-webhook-gate.js

@@ -0,0 +1,295 @@
+'use strict';
+
+// adapters/gcp/dfcx-webhook-gate.js
+// -----------------------------------------------------------------------------
+// ThumbGate Enterprise — Dialogflow CX fulfillment webhook guardrail.
+//
+// Routes a Dialogflow CX (DFCX) fulfillment request through ThumbGate's
+// pre-action gate engine BEFORE the real fulfillment side-effect runs (DB/CRM/
+// billing write). If a configured policy gate denies the action, or the action
+// is a known same-session repeat, the side-effect is blocked and a safe DFCX
+// WebhookResponse is returned instead of executing it.
+//
+// Design: ThumbGate is a *guard in front of* the customer's existing fulfillment
+// function — it decides whether that function is allowed to run. It does not
+// replace it, mutate Playbooks, or call any Google API itself.
+//
+// This enterprise adapter is also listed in package.json "files" because
+// src/api/server.js loads it for the local enterprise Dialogflow dashboard routes.
+// The same module can still be deployed as Cloud Run / Cloud Functions middleware.
+// -----------------------------------------------------------------------------
+
+const path = require('path');
+
+const REPO_ROOT = path.join(__dirname, '..', '..');
+const gates = require(path.join(REPO_ROOT, 'scripts', 'gates-engine'));
+
+// Risk scorer is optional: it needs a trained model on disk. Degrade to null.
+let riskScorer = null;
+try {
+  riskScorer = require(path.join(REPO_ROOT, 'scripts', 'risk-scorer'));
+} catch (_) {
+  riskScorer = null;
+}
+
+// Deterministic stringify so the same parameter object always yields the same
+// action id (used for same-session repeat detection).
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']';
+  const keys = Object.keys(value).sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}';
+}
+
+// Map a DFCX WebhookRequest into a ThumbGate (toolName, toolInput) action.
+// DFCX fulfillment tag -> toolName ("dfcx:<tag>"); session parameters -> toolInput.
+// Supports both camelCase (standard DFCX) and snake_case (legacy/internal) formatting.
+function mapDfcxToAction(reqBody) {
+  const body = reqBody || {};
+  const fulfillmentInfo = body.fulfillmentInfo || body.fulfillment_info || {};
+  const tag = fulfillmentInfo.tag || 'unknown';
+  const sessionInfo = body.sessionInfo || body.session_info || {};
+  const params = sessionInfo.parameters || {};
+  const sessionId = sessionInfo.session || '';
+  return {
+    tag,
+    toolName: 'dfcx:' + tag,
+    toolInput: params,
+    sessionId,
+  };
+}
+
+// A DFCX webhook is fully untrusted (internet-facing), unlike a local coding
+// agent. These allowlists reject anything that could carry shell/path
+// metacharacters before the action ever reaches the gate engine.
+const SAFE_TOKEN = /^[A-Za-z0-9._\s-]{1,64}$/; // fulfillment tags, parameter names
+const SAFE_VALUE = /^[^`\;|&<>]{0,2048}$/;    // parameter string values (allow standard punctuation, block command injection)
+
+// Evaluate whether a DFCX fulfillment should be allowed to execute.
+// Returns { allowed, decision, gate, message, severity, repeat, risk, action }.
+function evaluateDfcxFulfillment(reqBody, opts = {}) {
+  const raw = mapDfcxToAction(reqBody);
+
+  // 0) Validate the untrusted webhook input and rebuild a SAFE action inline,
+  //    before any value reaches the gate engine. Block on any unsafe token/value
+  //    so attacker-controlled input cannot reach a path/command sink downstream.
+  const blockedUnsafe = (reason) => ({
+    allowed: false,
+    decision: 'deny',
+    gate: 'dfcx-unsafe-input',
+    message: 'The request contained unsafe input and was blocked.',
+    severity: 'critical',
+    repeat: false,
+    risk: null,
+    action: { tag: String(raw.tag), toolName: 'dfcx:unsafe', toolInput: {}, sessionId: raw.sessionId },
+    reason,
+  });
+  const tag = String(raw.tag);
+  if (!SAFE_TOKEN.test(tag)) return blockedUnsafe('unsafe fulfillment tag');
+  const toolName = 'dfcx:' + tag;
+  const toolInput = {};
+  const rawParams = raw.toolInput && typeof raw.toolInput === 'object' ? raw.toolInput : {};
+  for (const key of Object.keys(rawParams)) {
+    if (!SAFE_TOKEN.test(key)) return blockedUnsafe('unsafe parameter name');
+    const value = rawParams[key];
+    if (typeof value === 'string') {
+      if (!SAFE_VALUE.test(value)) return blockedUnsafe('unsafe parameter value');
+      toolInput[key] = value;
+    } else if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
+      toolInput[key] = value;
+    }
+    // non-scalar values are intentionally dropped (never forwarded downstream).
+  }
+  const action = { tag, toolName, toolInput, sessionId: raw.sessionId };
+
+  // 1) Configured policy gates. The pilot configures DFCX-relevant gates (e.g.
+  //    "block dfcx:process-refund when amount > limit and not approved"). With no
+  //    custom config this is simply a no-op (allow).
+  let gateResult = null;
+  try {
+    gateResult = gates.evaluateGates(toolName, toolInput, opts.configPath);
+  } catch (_) {
+    gateResult = null;
+  }
+  const denied = Boolean(gateResult && gateResult.decision === 'deny');
+
+  // 2) Same-session repeat detection — works with zero custom config.
+  const actionId = action.toolName + ':' + stableStringify(action.toolInput);
+  let repeat = false;
+  if (typeof gates.hasAction === 'function') {
+    try { repeat = Boolean(gates.hasAction(actionId)); } catch (_) { repeat = false; }
+  }
+  if (typeof gates.trackAction === 'function') {
+    try { gates.trackAction(actionId, { source: 'dfcx', tag: action.tag }); } catch (_) { /* non-fatal */ }
+  }
+
+  // 3) Optional risk score (best-effort; null when no model is trained).
+  let risk = null;
+  if (riskScorer && typeof riskScorer.predictRisk === 'function') {
+    try {
+      const candidate = typeof riskScorer.buildRiskCandidate === 'function'
+        ? riskScorer.buildRiskCandidate({ toolName: action.toolName, toolInput: action.toolInput })
+        : { toolName: action.toolName, toolInput: action.toolInput };
+      const r = riskScorer.predictRisk(candidate);
+      risk = typeof r === 'number' ? r : (r && typeof r.risk === 'number' ? r.risk : null);
+    } catch (_) {
+      risk = null;
+    }
+  }
+
+  const blockOnRepeat = opts.blockOnRepeat !== false && repeat;
+  const allowed = !denied && !blockOnRepeat;
+
+  return {
+    allowed,
+    decision: allowed ? 'allow' : 'deny',
+    gate: denied ? gateResult.gate : (blockOnRepeat ? 'dfcx-repeat-action' : null),
+    message: denied
+      ? gateResult.message
+      : (blockOnRepeat ? 'This action was already attempted in this session and is blocked as a repeat.' : null),
+    severity: denied ? gateResult.severity : (blockOnRepeat ? 'high' : null),
+    repeat,
+    risk,
+    action,
+  };
+}
+
+// Build a DFCX WebhookResponse that safely halts the turn without side-effects.
+// Supports both camelCase (standard DFCX) and snake_case (legacy/internal) formatting.
+function buildBlockResponse(evaluation, opts = {}) {
+  const message = opts.blockedMessage
+    || 'This request was held by a safety policy and was not completed. A team member may follow up.';
+  const payload = {
+    fulfillment_response: { messages: [{ text: { text: [message] } }] },
+    fulfillmentResponse: { messages: [{ text: { text: [message] } }] },
+    session_info: {
+      parameters: {
+        thumbgate_blocked: true,
+        thumbgate_gate: evaluation.gate || null,
+        thumbgate_severity: evaluation.severity || null,
+      },
+    },
+    sessionInfo: {
+      parameters: {
+        thumbgate_blocked: true,
+        thumbgate_gate: evaluation.gate || null,
+        thumbgate_severity: evaluation.severity || null,
+      },
+    },
+  };
+  return payload;
+}
+
+// Annotate an allowed (passed-through) response so downstream flows can observe
+// that ThumbGate evaluated and permitted the turn. Never throws on odd shapes.
+// Populates both camelCase and snake_case variants to ensure compatibility.
+function annotateAllowed(response, evaluation) {
+  const base = response && typeof response === 'object' ? response : {};
+  
+  const sessionInfo = base.sessionInfo || base.session_info || {};
+  const params = sessionInfo.parameters && typeof sessionInfo.parameters === 'object' ? sessionInfo.parameters : {};
+  
+  const updatedParams = Object.assign({}, params, {
+    thumbgate_blocked: false,
+    thumbgate_risk: evaluation.risk,
+  });
+  
+  const updatedSessionInfo = Object.assign({}, sessionInfo, {
+    parameters: updatedParams,
+  });
+  
+  const updated = Object.assign({}, base, {
+    session_info: updatedSessionInfo,
+    sessionInfo: updatedSessionInfo,
+  });
+  
+  if (base.fulfillment_response) {
+    updated.fulfillmentResponse = base.fulfillment_response;
+  } else if (base.fulfillmentResponse) {
+    updated.fulfillment_response = base.fulfillmentResponse;
+  }
+  
+  return updated;
+}
+
+// Guard a DFCX webhook: run the gate; only invoke the real fulfillment when
+// allowed. `fulfill(reqBody) -> WebhookResponse` is the customer's existing
+// fulfillment function. Returns { blocked, response, evaluation }.
+async function guardDfcxWebhook(reqBody, fulfill, opts = {}) {
+  const evaluation = evaluateDfcxFulfillment(reqBody, opts);
+  if (!evaluation.allowed) {
+    return { blocked: true, response: buildBlockResponse(evaluation, opts), evaluation };
+  }
+  const fulfilled = typeof fulfill === 'function'
+    ? await fulfill(reqBody)
+    : { fulfillment_response: { messages: [] } };
+  return { blocked: false, response: annotateAllowed(fulfilled, evaluation), evaluation };
+}
+
+// Reject bodies larger than this. A DFCX WebhookRequest is small (a few KB); an
+// unbounded reader on an internet-facing endpoint is a memory-exhaustion vector.
+const MAX_BODY_BYTES = 1024 * 1024; // 1 MiB
+
+// Read a JSON request body from a Node IncomingMessage stream, with a hard size
+// cap so a malicious/misconfigured caller cannot exhaust memory.
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = '';
+    let bytes = 0;
+    let aborted = false;
+    req.on('data', (chunk) => {
+      if (aborted) return;
+      bytes += chunk.length;
+      if (bytes > MAX_BODY_BYTES) {
+        aborted = true;
+        const err = new Error('request body exceeds ' + MAX_BODY_BYTES + ' bytes');
+        err.statusCode = 413;
+        try { req.destroy(); } catch (_) { /* ignore */ }
+        return reject(err);
+      }
+      raw += chunk;
+    });
+    req.on('end', () => {
+      if (aborted) return;
+      if (!raw) return resolve({});
+      try { resolve(JSON.parse(raw)); } catch (e) { reject(e); }
+    });
+    req.on('error', reject);
+  });
+}
+
+// Plain Node HTTP handler for Cloud Run / Cloud Functions (no framework dep).
+function createHttpHandler(fulfill, opts = {}) {
+  return async function handler(req, res) {
+    try {
+      const body = req && req.body && typeof req.body === 'object'
+        ? req.body
+        : await readJsonBody(req);
+      const { response, evaluation } = await guardDfcxWebhook(body, fulfill, opts);
+      if (typeof opts.onDecision === 'function') {
+        try { opts.onDecision(evaluation); } catch (_) { /* observability must not break the turn */ }
+      }
+      res.statusCode = 200;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify(response));
+    } catch (err) {
+      // Log internally for operators; never leak error/stack details to the
+      // external caller (Dialogflow CX / the open internet).
+      try { console.error('thumbgate-dfcx-gate error:', err); } catch (_) { /* ignore */ }
+      res.statusCode = 500;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ error: 'thumbgate-dfcx-gate-failure' }));
+    }
+  };
+}
+
+module.exports = {
+  mapDfcxToAction,
+  evaluateDfcxFulfillment,
+  buildBlockResponse,
+  annotateAllowed,
+  guardDfcxWebhook,
+  createHttpHandler,
+  // exposed for tests
+  stableStringify,
+};

package/adapters/letta/README.md

@@ -0,0 +1,41 @@
+# Letta Adapter
+
+Letta is a stateful-agent runtime with persistent memory, MCP tools, custom server tools, and client-side tool execution. ThumbGate should not compete with that memory surface. ThumbGate should sit underneath it as the deterministic local enforcement layer.
+
+## Integration Pattern
+
+Use `thumbgate-letta-adapter.js` to wrap Letta tool execution:
+
+1. Letta agent proposes a tool call.
+2. The wrapper normalizes the Letta event into ThumbGate's provider-action schema.
+3. Your app calls ThumbGate's local gate-check transport.
+4. If ThumbGate blocks or requires approval, the tool executor is never called.
+5. If allowed, the original Letta tool executes normally.
+
+This works for the two practical Letta surfaces:
+
+- **MCP tools**: Letta forwards the tool call through the Letta server to an MCP server. Wrap the forwarding boundary or expose the downstream tool through a ThumbGate-guarded MCP server.
+- **Client tools**: Letta asks your client application to execute a tool locally. Wrap the client tool handler with `createLettaToolGuard`.
+
+## Example
+
+```js
+const { createLettaToolGuard } = require('./thumbgate-letta-adapter');
+
+const guardedTool = createLettaToolGuard({
+  gateCheck: async (normalizedAction) => thumbgateGateCheck(normalizedAction),
+  executeTool: async (lettaEvent) => runOriginalTool(lettaEvent),
+});
+
+await guardedTool({
+  agentId: 'agent-123',
+  clientTool: {
+    name: 'shell',
+    input: { command: 'git push --force origin main' },
+  },
+});
+```
+
+## Positioning
+
+Letta helps agents remember and operate with state. ThumbGate helps teams decide what those agents are allowed to do next. The moat is adapter coverage: ThumbGate works under memory-first runtimes instead of asking buyers to replace them.