thumbgate 1.27.6 → 1.27.7

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

package/.well-known/llms.txt

@@ -15,6 +15,7 @@
 - CLAUDE.md and .cursorrules files are suggestions agents can ignore
 - No memory between sessions means no learning from corrections
 - Teams have no shared safety rules across developers
+- AI crawlers and agents create machine traffic without proving buyer intent; teams need AI-discoverable proof plus runtime gates before internal agents act
 
 ## How it works
 
@@ -51,9 +52,9 @@ npx thumbgate init --agent claude-code
 - ChatGPT App / GPT Action: https://thumbgate.ai/chatgpt-app
 - Free GPT: advice, checkpointing, and setup help in ChatGPT
 - Codex Plugin: https://thumbgate.ai/codex-plugin
-- Free local CLI: 5 captures/day, 25 total captures, up to 3 active auto-promoted prevention rules, and local Pre-Action Checks after install (recall and lesson search are Pro-only)
+- Free local CLI: 2 captures/day, 10 total captures, up to 3 active auto-promoted prevention rules, and local Pre-Action Checks after install (recall and lesson search are Pro-only)
 - Pro: $19/mo or $149/yr — personal enforcement proof, local dashboard, check debugger, DPO export, synced lessons/rules across machines, and review-ready exports
-- Team: $49/seat/mo, 3-seat minimum after intake — shared lessons, org visibility, approval boundaries, and rollout proof
+- Enterprise: custom pricing, scoped after intake — shared hosted lesson database, org-wide dashboard, GCP/DFCX guardrails, VPC gating, and white-glove workflow hardening sprints
 
 ## Links
 
@@ -63,6 +64,9 @@ npx thumbgate init --agent claude-code
 - Agent discovery: https://thumbgate.ai/.well-known/mcp.json
 - Progressive tool index: https://thumbgate.ai/.well-known/mcp/tools.json
 - Context footprint report: https://thumbgate.ai/.well-known/mcp/footprint.json
+- Headroom context compression guardrails: https://thumbgate.ai/guides/headroom-context-compression-guardrails
+- Sovereign coding model guardrails: https://thumbgate.ai/guides/sovereign-coding-model-guardrails
+- Agentic web governance: https://thumbgate.ai/guides/agentic-web-governance
 - AI Mode ads and agent governance: https://thumbgate.ai/guides/ai-mode-ads-agent-governance
 - MCP tool governance: https://thumbgate.ai/guides/mcp-tool-governance
 - AI agent pre-action approval gates: https://thumbgate.ai/guides/ai-agent-pre-action-approval-gates

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

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

@@ -12,6 +12,10 @@ ThumbGate is the local-first firewall for AI coding agents. It runs in the PreTo
 
 The product is a self-improving enforcement layer: thumbs-down feedback, prompt evaluation, and proof from prior runs become prevention rules that permanently stop repeated failures before the next tool call.
 
+<p align="center">
+  <img src="docs/media/thumbgate-demo.gif" alt="ThumbGate blocking an AI agent's dangerous commands (rm -rf, force-push, chmod 777) in real time, while letting safe commands through" width="820" />
+</p>
+
 ```
   Agent tries:   rm -rf tests/
   ThumbGate:     ⛔ BLOCKED — "Never delete test directories"
@@ -24,7 +28,7 @@ The product is a self-improving enforcement layer: thumbs-down feedback, prompt
 npx thumbgate init   # auto-detects your agent, wires hooks, 30 seconds
 ```
 
-Works with **Claude Code, Cursor, Codex, Gemini CLI, Amp, Cline, OpenCode** and any MCP-compatible agent. Free tier: 5 feedback captures/day (25 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) — unlimited rules, history-aware lessons, feedback sessions, dashboard, DPO export. Enterprise (custom pricing, scoped after intake) adds a shared hosted lesson DB, org dashboard, and shared org-wide enforcement.
+Works with **Claude Code, Cursor, Codex, Gemini CLI, Amp, Cline, OpenCode** and any MCP-compatible agent. 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) — unlimited rules, history-aware lessons, feedback sessions, dashboard, DPO export. Enterprise (custom pricing, scoped after intake) adds a shared hosted lesson DB, org dashboard, and shared org-wide enforcement.
 
 [![CI](https://github.com/IgorGanapolsky/ThumbGate/actions/workflows/ci.yml/badge.svg)](https://github.com/IgorGanapolsky/ThumbGate/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/thumbgate)](https://www.npmjs.com/package/thumbgate)
@@ -53,6 +57,24 @@ In that stack, ThumbGate is the pre-action gate between generated intent and exe
 
 ---
 
+## Discoverable slash-commands — the guardrail layer for spec-driven agents
+
+Spec-driven agent frameworks like **GSD** (get-shit-done) and **GitHub Spec Kit** are great at *planning and generating* work — they expose dozens of discoverable `/gsd-*` / `/specify` commands in the agent command palette. ThumbGate is the **guardrail layer for spec-driven agents**: it sits *after* the plan, on the boundary between a generated tool call and its execution. It works **alongside GSD / Spec-Kit, not instead of them** — they decide *what* to build; ThumbGate enforces *what the agent must never do while building it*.
+
+`npx thumbgate init` installs these commands into your agent's palette (`.claude/commands/`, `.gemini/commands/`, `.antigravitycli/commands/`) so the enforcement layer is as browsable as the planning layer:
+
+| Command | What it does | Wraps (existing capability) |
+|---------|--------------|------------------------------|
+| `/thumbgate-guard` | Turn the last agent mistake into a hard prevention rule | `capture_feedback` + `thumbgate force-gate` |
+| `/thumbgate-rules` | List the active prevention rules + lessons guarding this repo | `prevention_rules`, `get_reliability_rules`, `search_lessons` |
+| `/thumbgate-blocked` | Show what's actually been blocked — gate stats + enforcement matrix | `gate_stats`, `enforcement_matrix` |
+| `/thumbgate-protect` | Show branch/release governance; grant a scoped, expiring approval | `get_branch_governance`, `approve_protected_action` |
+| `/thumbgate-doctor` | Health-check the wiring (hooks, MCP, agent-readiness) | `thumbgate doctor` |
+
+Each is a thin wrapper over an existing MCP tool or CLI command — **no new enforcement logic, just discoverability**.
+
+---
+
 ## 🎬 90-second demo
 
 Watch the force-push scenario: agent tries to `git push --force`, one thumbs-down, next session it's blocked — zero tokens spent on the repeat.
@@ -185,6 +207,26 @@ Hand-rolled hooks are the right tool for a small, static denylist you maintain b
 
 Prompt engineering still matters, but it is only the starting point. ThumbGate adds prompt evaluation on top: proof lanes, benchmarks, and self-heal checks tell you whether your prompt and workflow actually held up under execution instead of leaving you to guess from vibes. Run `npx thumbgate eval --from-feedback --write-report=.thumbgate/prompt-eval-proof.md` to turn real thumbs-up/down feedback into reusable eval cases and a buyer-ready proof report.
 
+### 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.
+
+```mermaid
+flowchart LR
+    A["Agent about to run<br/>a tool call"] --> B{"Literal / AST match<br/>on an active rule?"}
+    B -- "exact match" --> D["Deterministic gate decision<br/>(no model, on-device)"]
+    B -- "no exact match, but<br/>semantically near a<br/>blocked pattern" --> C["Local CPU embeddings<br/>bge-small via LanceDB<br/>(no external API)"]
+    C --> D
+    D -- "known-bad" --> E["⛔ BLOCK before execution"]
+    D -- "safe" --> F["✓ Allow"]
+```
+
+- **Deterministic first.** Most decisions are a literal or AST pattern match against your active rules — sub-millisecond, on-device, no embeddings.
+- **Local semantic fallback.** When an action isn't on the literal block list but is semantically near one you've blocked before, ThumbGate searches the rule corpus with CPU-only `bge-small` embeddings via LanceDB — still local, still no external API call.
+- **No LLM on the enforcement path.** The gate never calls a model to decide block/allow. Thompson Sampling only tunes soft-rule confidence weights; hard rules always fire deterministically (see Layer 2).
+
+The fastest network round-trip is the one you never make: enforcement is fully local, so it adds negligible latency to the agent loop — no cloud retrieval, no inference hop, no data leaving the machine.
+
 ### Managed model benchmark lane
 
 When a new managed model drops, do not swap ThumbGate over on vendor claims alone. Rank it against the actual ThumbGate workload first:
@@ -342,6 +384,8 @@ npx thumbgate model-candidates --workload=dashboard-analysis --provider=openai -
 npx thumbgate native-messaging-audit  # inspect local browser bridges and extension hosts
 npx thumbgate dashboard --open                                  # open local project-scoped dashboard in browser
 thumbgate-dashboard                                             # standalone browser dashboard shortcut (run '/project:thumbgate-dashboard' in Claude/Grok)
+npx thumbgate check-update                                      # check if a new version is available on npm/GitHub
+npx thumbgate self-update                                       # update ThumbGate to the latest version globally
 npx thumbgate serve      # start MCP server on stdio
 npx thumbgate bench      # run reliability benchmark
 npx thumbgate bench --programbench-smoke  # include cleanroom whole-repo proof lane
@@ -382,7 +426,7 @@ If you change MCP or hook settings, restart the affected agent session so Claude
 | | Free | Pro ($19/mo) | Enterprise |
 |---|---|---|---|
 | Local CLI + enforced checks | ✅ | ✅ | ✅ |
-| Feedback captures | 5/day (25 total) | Unlimited | Unlimited |
+| Feedback captures | 2/day (10 total) | Unlimited | Unlimited |
 | Active auto-promoted prevention rules | 3 | Unlimited | Unlimited |
 | MCP agent integrations | All | All | All |
 | Personal dashboard | — | ✅ | ✅ |
@@ -396,7 +440,7 @@ If you change MCP or hook settings, restart the affected agent session so Claude
 | Compliance audit export | — | — | ✅ |
 | Dedicated onboarding + SLA | — | — | ✅ |
 
-The free tier gives you 5 feedback captures/day (25 total) and up to 3 active auto-promoted prevention rules — enough to make ThumbGate part of your daily flow before you upgrade. MCP integrations for all agents (Claude Code, Cursor, Codex, Gemini, Amp, Cline, OpenCode) ship free.
+The free tier gives you 2 feedback captures/day (10 total) and up to 3 active auto-promoted prevention rules — enough to make ThumbGate part of your daily flow before you upgrade. MCP integrations for all agents (Claude Code, Cursor, Codex, Gemini, Amp, Cline, OpenCode) ship free.
 
 Pro ($19/mo or $149/yr) removes the rule cap and adds history-aware lesson recall, lesson search, DPO export, and a personal dashboard. Enterprise (custom pricing, scoped after intake) adds a shared hosted lesson DB, org dashboard, and shared enforcement across the org, plus regulatory gate templates (legal intake, financial compliance, healthcare), custom policy layers scoped to firm/practice-area, compliance audit export, and dedicated onboarding with SLA.
 
@@ -487,7 +531,7 @@ curl -X POST http://localhost:3456/v1/dpo/export \
 | Layer | Technology |
 |-------|-----------|
 | **Storage** | SQLite + FTS5, LanceDB vectors, JSONL logs |
-| **Capture** | 5/day, 25 total on Free; unlimited on Pro, Team, and Enterprise |
+| **Capture** | 2/day, 10 total on Free; unlimited on Pro, Team, and Enterprise |
 | **Intelligence** | MemAlign dual recall, Thompson Sampling |
 | **Enforcement** | PreToolUse hook engine, Checks config |
 | **Interfaces** | MCP stdio, HTTP API, CLI (Node.js >=18) |
@@ -575,7 +619,7 @@ Those are suggestions the agent can ignore. ThumbGate checks are enforced — th
 If it supports MCP or pre-action hooks, yes. Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, Amp, Cline, OpenCode all work out of the box.
 
 **Is it free?**
-The free tier gives you 5 feedback captures/day, 25 total captures, and up to 3 active auto-promoted prevention rules — enough for solo devs to prove a blocked repeat before upgrading. MCP integrations ship free for every agent.
+The free tier gives you 2 feedback captures/day, 10 total captures, and up to 3 active auto-promoted prevention rules — enough for solo devs to prove a blocked repeat before upgrading. MCP integrations ship free for every agent.
 
 Pro ($19/mo or $149/yr) removes the rule cap and adds history-aware lesson recall, lesson search, and a personal dashboard. Enterprise (custom pricing, scoped after intake) adds a shared hosted lesson DB, org dashboard, and shared enforcement.
 

package/adapters/claude/.mcp.json

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

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.

package/adapters/letta/thumbgate-letta-adapter.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+'use strict';
+
+const { normalizeProviderAction } = require('../../scripts/provider-action-normalizer');
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    const text = String(value || '').trim();
+    if (text) return text;
+  }
+  return '';
+}
+
+function extractLettaToolCall(input = {}) {
+  const event = asObject(input);
+  const toolCall = asObject(event.toolCall || event.tool_call || event.lettaToolCall);
+  const functionCall = asObject(toolCall.function || event.function);
+  const mcp = asObject(event.mcp || event.mcpToolCall);
+  const clientTool = asObject(event.clientTool || event.client_tool);
+  const params = asObject(event.params);
+
+  const name = firstString(
+    event.toolName,
+    event.name,
+    toolCall.name,
+    functionCall.name,
+    clientTool.name,
+    mcp.name,
+    params.name
+  );
+  const args = asObject(
+    event.arguments
+      || event.args
+      || event.input
+      || toolCall.arguments
+      || toolCall.input
+      || functionCall.arguments
+      || clientTool.arguments
+      || clientTool.input
+      || mcp.arguments
+      || params.arguments
+  );
+
+  return {
+    id: firstString(event.id, event.toolCallId, event.tool_call_id, toolCall.id, clientTool.id),
+    name,
+    arguments: args,
+    server: firstString(event.mcpServer, mcp.server, params.server),
+    surface: firstString(event.surface, event.executionSurface, clientTool.name ? 'client-tool' : mcp.name || params.name ? 'mcp-tool' : 'server-tool'),
+  };
+}
+
+function normalizeLettaAction(input = {}) {
+  const event = asObject(input);
+  const toolCall = extractLettaToolCall(event);
+
+  const normalized = normalizeProviderAction({
+    ...event,
+    provider: 'letta',
+    toolCall: {
+      id: toolCall.id,
+      name: toolCall.name,
+      input: toolCall.arguments,
+    },
+    toolName: toolCall.name,
+    input: toolCall.arguments,
+    mcpServer: toolCall.server,
+  });
+
+  return {
+    ...normalized,
+    provider: 'letta',
+    agentRuntime: 'letta',
+    letta: {
+      agentId: firstString(event.agentId, event.agent_id),
+      messageId: firstString(event.messageId, event.message_id),
+      surface: toolCall.surface,
+      toolCallId: toolCall.id,
+    },
+  };
+}
+
+function normalizeGateDecision(decision = {}) {
+  const value = asObject(decision);
+  const raw = firstString(value.decision, value.mode, value.action, value.status).toLowerCase();
+  const blocked = value.allowed === false
+    || value.accepted === false
+    || value.blocked === true
+    || ['block', 'deny', 'denied', 'reject', 'rejected'].includes(raw);
+  const approvalRequired = value.requiresApproval === true || raw === 'approve';
+  return {
+    allowed: !blocked && !approvalRequired,
+    blocked,
+    approvalRequired,
+    reason: firstString(value.reason, value.message, Array.isArray(value.reasons) ? value.reasons.join('; ') : ''),
+    raw: value,
+  };
+}
+
+function createLettaToolGuard({ gateCheck, executeTool, onDecision } = {}) {
+  if (typeof gateCheck !== 'function') {
+    throw new TypeError('createLettaToolGuard requires a gateCheck function');
+  }
+  if (typeof executeTool !== 'function') {
+    throw new TypeError('createLettaToolGuard requires an executeTool function');
+  }
+
+  return async function guardedLettaTool(input = {}) {
+    const normalizedAction = normalizeLettaAction(input);
+    const decision = normalizeGateDecision(await gateCheck(normalizedAction));
+    if (typeof onDecision === 'function') {
+      await onDecision({ normalizedAction, decision });
+    }
+    if (!decision.allowed) {
+      const error = new Error(decision.reason || 'ThumbGate blocked this Letta tool call before execution.');
+      error.code = decision.approvalRequired ? 'THUMBGATE_APPROVAL_REQUIRED' : 'THUMBGATE_BLOCKED';
+      error.thumbgate = { normalizedAction, decision };
+      throw error;
+    }
+    return executeTool(input, { normalizedAction, decision });
+  };
+}
+
+module.exports = {
+  createLettaToolGuard,
+  extractLettaToolCall,
+  normalizeGateDecision,
+  normalizeLettaAction,
+};

package/adapters/mcp/server-stdio.js

@@ -231,7 +231,7 @@ const {
   finalizeSession: finalizeFeedbackSession,
 } = require('../../scripts/feedback-session');
 
-const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.27.6' };
+const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.27.7' };
 const COMMERCE_CATEGORIES = [
   'product_recommendation',
   'brand_compliance',
@@ -674,6 +674,21 @@ function buildEstimateUncertaintyResponse(args = {}) {
 
 async function callTool(name, args = {}) {
   assertToolAllowed(name, getActiveMcpProfile());
+
+  // Validate tool input contract against schema
+  const { TOOLS } = require('../../scripts/tool-registry');
+  const toolDef = TOOLS.find(t => t.name === name);
+  if (toolDef && toolDef.inputSchema) {
+    const { validateToolContract } = require('../../scripts/tool-contract-validator');
+    const validation = validateToolContract(toolDef.inputSchema, args);
+    if (!validation.valid) {
+      const err = new Error(`Tool contract violation on '${name}': ${validation.errors.join('; ')}`);
+      err.errorCategory = 'contract';
+      err.isRetryable = false;
+      throw err;
+    }
+  }
+
   if (name !== 'workflow_sentinel' && process.env.THUMBGATE_DISABLE_MCP_FIREWALL !== '1') {
     const firewallResult = (await evaluateGatesAsync(name, args)) || evaluateSecretGuard({ tool_name: name, tool_input: args });
     if (firewallResult && firewallResult.decision === 'deny') {

package/adapters/opencode/opencode.json

@@ -7,7 +7,7 @@
         "npx",
         "--yes",
         "--package",
-        "thumbgate@1.27.6",
+        "thumbgate@1.27.7",
         "thumbgate",
         "serve"
       ],

package/adapters/policy-engine/ethicore-guardian-client.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+'use strict';
+
+const DEFAULT_ENDPOINT = 'https://api.oraclestechnologies.com/v1/guardian/analyze';
+
+function requireApiKey(env = process.env) {
+  const key = env.ETHICORE_API_KEY || env.GUARDIAN_API_KEY || env.ORACLES_GUARDIAN_API_KEY;
+  if (!key) {
+    throw new Error('ETHICORE_API_KEY env var is required');
+  }
+  return key;
+}
+
+async function analyzeText(text, options = {}) {
+  if (!String(text || '').trim()) {
+    throw new Error('analyzeText requires text');
+  }
+
+  const env = options.env || process.env;
+  const endpoint = options.endpoint || env.ETHICORE_GUARDIAN_ENDPOINT || DEFAULT_ENDPOINT;
+  const apiKey = options.apiKey || requireApiKey(env);
+  const fetchImpl = options.fetch || fetch;
+
+  const response = await fetchImpl(endpoint, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ text }),
+  });
+
+  const bodyText = await response.text();
+  let body = bodyText;
+  try {
+    body = bodyText ? JSON.parse(bodyText) : {};
+  } catch {
+    // Keep non-JSON body for diagnostics.
+  }
+
+  if (!response.ok) {
+    throw new Error(`Ethicore Guardian API ${response.status}: ${typeof body === 'string' ? body : JSON.stringify(body)}`);
+  }
+
+  return body;
+}
+
+function createEthicorePolicyCheck(options = {}) {
+  return async function ethicorePolicyCheck(action = {}) {
+    const toolText = [
+      action.toolName,
+      action.actionType,
+      action.command,
+      action.path,
+      action.url,
+      action.input ? JSON.stringify(action.input) : '',
+    ].filter(Boolean).join('\n');
+
+    return analyzeText(toolText || JSON.stringify(action), options);
+  };
+}
+
+module.exports = {
+  DEFAULT_ENDPOINT,
+  analyzeText,
+  createEthicorePolicyCheck,
+  requireApiKey,
+};