thumbgate 1.26.7 → 1.27.2

package/scripts/seo-gsd.js

@@ -394,6 +394,58 @@ function buildSemanticPseoGuide() {
   });
 }
 
+const ZERO_TRUST_GUIDE_SPEC = Object.freeze({
+  slug: 'ai-coding-agent-zero-trust',
+  meta: {
+    query: 'zero trust for ai coding agents',
+    title: 'Zero Trust for AI Coding Agents | Enforce It at the Tool Call',
+    heroTitle: 'Zero Trust for AI Coding Agents, Enforced at the Tool Call',
+    heroSummary: 'Zero trust for agents means never trust, always verify; least privilege; assume breach. ThumbGate is the local-first way to enforce those principles for Claude Code, Cursor, and Codex — blocking dangerous tool calls before they run, and turning every thumbs-down into a prevention rule so the same mistake never repeats.',
+  },
+  takeaways: [
+    'Zero trust for agents means verifying every action at the boundary where it executes — the tool call — instead of trusting the model’s stated intent.',
+    'ThumbGate runs in the PreToolUse hook on your machine: rm -rf, secret writes, off-scope edits, and bad git push are blocked before execution (assume breach, least privilege).',
+    'Unlike static DIY hooks, ThumbGate learns — a thumbs-down becomes an auto-promoted prevention rule that holds across every session, model, and agent.',
+  ],
+  sections: [
+    ['paragraphs', 'Why AI coding agents need zero trust at the tool call', [
+      'A coding agent reads files, runs shell commands, calls APIs, and pushes code with minimal human approval at each step. If it is manipulated, misconfigured, or simply wrong, the blast radius is whatever it can execute — and unlike a human, it does not pause to question a suspicious request.',
+      'Zero-trust security for agents adapts three principles to this reality: never trust, always verify; least privilege; and assume breach. The practical place to apply them is the action boundary — the moment before a tool call runs — not the model’s prompt or its good intentions.',
+    ]],
+    ['bullets', 'ThumbGate vs. rolling your own Claude Code hooks', [
+      'Static hooks and community repos do pattern-matching you write and maintain by hand, per machine, per project. ThumbGate ships the same blocking and adds a learning layer on top.',
+      'A thumbs-down on a bad action becomes an auto-promoted prevention rule — the repeat is blocked automatically next time, on every session and every agent, with zero extra config.',
+      'Local-first: enforcement runs in the PreToolUse hook on the developer machine, not a server-side gateway, so it works the moment you npx thumbgate init.',
+      'Works across Claude Code, Cursor, Codex, Gemini, Amp, Cline, and OpenCode — one rule set, every MCP-compatible agent.',
+    ]],
+    ['paragraphs', 'How ThumbGate maps to the zero-trust principles', [
+      'Never trust, always verify: every high-risk tool call is checked against prevention rules and workflow shape before it executes. Least privilege: task scope and approval gates keep an agent inside its declared blast radius. Assume breach: dangerous commands are blocked before they touch the disk, so a compromised or confused agent cannot do damage on the way to being caught.',
+      'This is enforcement, not observability. ThumbGate decides at the tool call whether the action runs — which is exactly where zero-trust controls have to live for autonomous agents.',
+    ]],
+  ],
+  faq: [
+    [
+      'Isn’t this just Claude Code’s built-in hooks?',
+      'Native hooks and community repos do static pattern-matching that you author and maintain per machine. ThumbGate adds the learning layer: a thumbs-down becomes a prevention rule that blocks the repeat automatically, across sessions and agents — the part static hooks cannot do.',
+    ],
+    [
+      'How does ThumbGate enforce zero trust for AI agents?',
+      'It applies the core principles at the tool-call boundary on your machine: never trust, always verify (every risky action is checked before it runs), least privilege (task scope and approval gates), and assume breach (dangerous calls are blocked before they touch disk).',
+    ],
+  ],
+  relatedPaths: ['/guides/pre-action-checks', '/guides/agent-harness-optimization'],
+});
+
+function buildZeroTrustGuide() {
+  return preActionGuide(ZERO_TRUST_GUIDE_SPEC.slug, {
+    ...ZERO_TRUST_GUIDE_SPEC.meta,
+    takeaways: ZERO_TRUST_GUIDE_SPEC.takeaways,
+    sections: ZERO_TRUST_GUIDE_SPEC.sections.map(([kind, heading, entries]) => buildSectionFromSpec(kind, heading, entries)),
+    faq: ZERO_TRUST_GUIDE_SPEC.faq.map(([question, text]) => answer(question, text)),
+    relatedPaths: ZERO_TRUST_GUIDE_SPEC.relatedPaths,
+  });
+}
+
 const PROXY_POINTER_RAG_GUARDRAILS_SPEC = Object.freeze({
   slug: 'proxy-pointer-rag-guardrails',
   meta: {
@@ -1536,6 +1588,7 @@ const PAGE_BLUEPRINTS = [
     relatedPaths: ['/compare/speclock', '/guides/claude-code-feedback'],
   },
   buildSemanticPseoGuide(),
+  buildZeroTrustGuide(),
   buildProxyPointerRagGuide(),
   buildRagPrecisionTuningGuide(),
   buildAiEngineeringStackGuide(),

package/scripts/thumbgate-bench.js

@@ -4,6 +4,7 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { expandFixturePlaceholders } = require('./secret-fixture-tokens');
 
 const ROOT = path.join(__dirname, '..');
 const DEFAULT_SUITE_PATH = path.join(ROOT, 'bench', 'thumbgate-bench.json');
@@ -180,6 +181,20 @@ function assertObject(value, label) {
   }
 }
 
+function expandScenarioFixturePlaceholders(value) {
+  if (typeof value === 'string') return expandFixturePlaceholders(value);
+  if (Array.isArray(value)) return value.map(expandScenarioFixturePlaceholders);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nestedValue]) => [
+        key,
+        expandScenarioFixturePlaceholders(nestedValue),
+      ]),
+    );
+  }
+  return value;
+}
+
 function loadScenarioSuite(filePath = DEFAULT_SUITE_PATH) {
   const suite = readJson(filePath);
   assertObject(suite, 'Scenario suite');
@@ -202,7 +217,7 @@ function loadScenarioSuite(filePath = DEFAULT_SUITE_PATH) {
       throw new Error(`Scenario ${id} has invalid expectedDecision`);
     }
     return {
-      ...scenario,
+      ...expandScenarioFixturePlaceholders(scenario),
       id,
       unsafe: Boolean(scenario.unsafe),
       positivePattern: Boolean(scenario.positivePattern),

package/scripts/tool-registry.js

@@ -161,6 +161,19 @@ const TOOLS = [
       required: ['toolName'],
     },
   }),
+  readOnlyTool({
+    name: 'ai_component_inventory',
+    description: 'Scan a project for AI/ML provider SDKs, agent frameworks, vector databases, Vertex/Gemini/Dialogflow CX usage, and model artifacts. Returns evidence suitable for enterprise AI inventory and ML-BOM review.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        rootDir: { type: 'string', description: 'Project root to scan. Defaults to the current process working directory.' },
+        format: { type: 'string', enum: ['summary', 'json', 'cyclonedx'], description: 'Response format. summary is compact text; json returns ThumbGate inventory; cyclonedx returns ML-BOM JSON.' },
+        maxFiles: { type: 'number', description: 'Maximum files to scan (default 2500).' },
+        includeSnippets: { type: 'boolean', description: 'Include matched source snippets in evidence. Defaults true.' },
+      },
+    },
+  }),
   readOnlyTool({
     name: 'search_thumbgate',
     description: 'Search raw ThumbGate state across feedback logs, ContextFS memory, prevention rules, and imported policy documents.',
@@ -818,6 +831,17 @@ const TOOLS = [
           items: { type: 'string' },
           description: 'Optional protected-file globs that require explicit approval before editing or publishing',
         },
+        workflowContract: {
+          type: 'object',
+          description: 'Optional deterministic workflow run contract. Supports workflowId, allowedBranches, blockedActions, requiredEvidence, and completionGate.',
+          properties: {
+            workflowId: { type: 'string' },
+            allowedBranches: { type: 'array', items: { type: 'string' } },
+            blockedActions: { type: 'array', items: { type: 'string' } },
+            requiredEvidence: { type: 'array', items: { type: 'string' } },
+            completionGate: { type: 'string' },
+          },
+        },
         repoPath: { type: 'string', description: 'Optional repo root used when evaluating git diff scope' },
         localOnly: { type: 'boolean', description: 'When true, also marks the task as local-only' },
         clear: { type: 'boolean', description: 'Clear the current task scope instead of setting one' },
@@ -1460,6 +1484,19 @@ const TOOLS = [
       },
     },
   }),
+  destructiveTool({
+    name: 'parallel_workflow',
+    description: 'Execute a parallel, multi-step subtask workflow to resolve an objective like a security audit, performance benchmark, or repository inspection.',
+    inputSchema: {
+      type: 'object',
+      required: ['objective'],
+      properties: {
+        objective: { type: 'string', description: 'The objective to plan and execute (e.g. security audit, performance benchmark)' },
+        concurrency: { type: 'number', description: 'Maximum parallel subtasks (default 3)' },
+        timeoutMs: { type: 'number', description: 'Timeout in milliseconds (default 60000)' },
+      },
+    },
+  }),
 ];
 
 // Normalize at export: guarantee EVERY tool carries a human-readable title and a

package/scripts/workflow-sentinel.js

@@ -69,6 +69,9 @@ function loadGovernanceState() {
     branchGovernance: raw && raw.branchGovernance && typeof raw.branchGovernance === 'object'
       ? raw.branchGovernance
       : null,
+    workflowContract: raw && raw.workflowContract && typeof raw.workflowContract === 'object'
+      ? raw.workflowContract
+      : null,
   };
 }
 
@@ -361,6 +364,116 @@ function formatFileList(files, limit = 5) {
   return `${items.slice(0, limit).join(', ')} (+${items.length - limit} more)`;
 }
 
+function normalizeStringList(values) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))];
+}
+
+function normalizeWorkflowContract(contract) {
+  if (!contract || typeof contract !== 'object') return null;
+  return {
+    workflowId: String(contract.workflowId || contract.workflow_id || '').trim() || null,
+    allowedBranches: normalizeStringList(contract.allowedBranches || contract.allowed_branches),
+    blockedActions: normalizeStringList(contract.blockedActions || contract.blocked_actions),
+    requiredEvidence: normalizeStringList(contract.requiredEvidence || contract.required_evidence),
+    completionGate: String(contract.completionGate || contract.completion_gate || '').trim() || null,
+  };
+}
+
+function commandMatchesPattern(command, pattern) {
+  const text = String(command || '');
+  const raw = String(pattern || '').trim();
+  if (!text || !raw) return false;
+  try {
+    return new RegExp(raw, 'i').test(text);
+  } catch {
+    return text.toLowerCase().includes(raw.toLowerCase());
+  }
+}
+
+function isCompletionLikeAction(command) {
+  return /\b(?:git\s+(?:commit|push)|gh\s+pr\s+(?:create|merge)|gh\s+release\s+create|npm\s+publish|yarn\s+publish|pnpm\s+publish)\b/i
+    .test(String(command || ''));
+}
+
+function collectEvidenceLabels(toolInput = {}, options = {}) {
+  const values = [];
+  for (const source of [
+    toolInput.evidence,
+    toolInput.evidenceLabels,
+    toolInput.proof,
+    toolInput.proofArtifacts,
+    toolInput.requiredEvidenceSatisfied,
+    options.evidence,
+    options.evidenceLabels,
+    options.proofArtifacts,
+  ]) {
+    if (Array.isArray(source)) values.push(...source);
+    else if (source && typeof source === 'object') values.push(...Object.keys(source).filter((key) => source[key]));
+    else if (typeof source === 'string') values.push(...source.split(/[,;\n]/));
+  }
+  return normalizeStringList(values).map((value) => value.toLowerCase());
+}
+
+function evaluateWorkflowContract(contractInput, context = {}) {
+  const contract = normalizeWorkflowContract(contractInput);
+  if (!contract) {
+    return {
+      active: false,
+      contract: null,
+      violations: [],
+      mode: 'allow',
+    };
+  }
+  const violations = [];
+  const command = String(context.command || '');
+  const currentBranch = String(context.currentBranch || '').trim();
+
+  const blockedAction = contract.blockedActions.find((pattern) => commandMatchesPattern(command, pattern));
+  if (blockedAction) {
+    violations.push({
+      code: 'blocked_action',
+      severity: 'block',
+      message: `Workflow contract blocks this action: ${blockedAction}`,
+      pattern: blockedAction,
+    });
+  }
+
+  if (contract.allowedBranches.length > 0 && currentBranch) {
+    const allowed = contract.allowedBranches.some((glob) => matchesAnyGlob(currentBranch, [glob]));
+    if (!allowed) {
+      violations.push({
+        code: 'branch_outside_contract',
+        severity: 'warn',
+        message: `Current branch ${currentBranch} is outside the workflow contract.`,
+        currentBranch,
+        allowedBranches: contract.allowedBranches,
+      });
+    }
+  }
+
+  if (contract.requiredEvidence.length > 0 && isCompletionLikeAction(command)) {
+    const evidenceLabels = collectEvidenceLabels(context.toolInput || {}, context.options || {});
+    const missing = contract.requiredEvidence.filter((label) => !evidenceLabels.includes(label.toLowerCase()));
+    if (missing.length > 0) {
+      violations.push({
+        code: 'missing_required_evidence',
+        severity: 'block',
+        message: `Workflow completion is missing required evidence: ${missing.join(', ')}`,
+        missingEvidence: missing,
+      });
+    }
+  }
+
+  const hasBlock = violations.some((violation) => violation.severity === 'block');
+  return {
+    active: true,
+    contract,
+    violations,
+    mode: hasBlock ? 'block' : violations.length > 0 ? 'warn' : 'allow',
+  };
+}
+
 function severityFromScore(score) {
   if (score >= 0.8) return 'critical';
   if (score >= 0.55) return 'high';
@@ -434,6 +547,7 @@ function scoreRisk({
   protectedSurface,
   costControl,
   workflowControl,
+  workflowContract,
   actionProfile,
 }) {
   const drivers = [];
@@ -590,6 +704,17 @@ function scoreRisk({
       );
     }
   }
+  if (workflowContract && workflowContract.active && workflowContract.violations.length > 0) {
+    for (const violation of workflowContract.violations) {
+      addDriver(
+        drivers,
+        `workflow_contract_${violation.code}`,
+        violation.severity === 'block' ? 0.38 : 0.18,
+        violation.message,
+        { workflowId: workflowContract.contract && workflowContract.contract.workflowId }
+      );
+    }
+  }
   if (memoryGuard && memoryGuard.mode && memoryGuard.mode !== 'allow') {
     addDriver(
       drivers,
@@ -663,6 +788,7 @@ function buildEvidence({
   normalizedAction,
   costControl,
   workflowControl,
+  workflowContract,
   actionProfile,
 }) {
   const evidence = [];
@@ -683,6 +809,15 @@ function buildEvidence({
       evidence.push(`Workflow control ${workflowControl.mode}: ${workflowControl.reasons.join(' ')}`);
     }
   }
+  if (workflowContract && workflowContract.active) {
+    const workflowId = workflowContract.contract && workflowContract.contract.workflowId
+      ? workflowContract.contract.workflowId
+      : 'unnamed';
+    evidence.push(`Workflow contract active: ${workflowId}.`);
+    for (const violation of workflowContract.violations.slice(0, 3)) {
+      evidence.push(`Workflow contract ${violation.severity}: ${violation.message}`);
+    }
+  }
   if (actionProfile && actionProfile.backgroundAgent) {
     evidence.push('Background or scheduled agent context detected for this action.');
   }
@@ -801,6 +936,7 @@ function buildRemediations({
   executionSurface,
   costControl,
   workflowControl,
+  workflowContract,
   actionProfile,
 }) {
   const remediations = [];
@@ -903,6 +1039,33 @@ function buildRemediations({
       'High token or cost estimates should be reviewed before the model/tool loop continues.'
     );
   }
+  if (workflowContract && workflowContract.active && workflowContract.violations.length > 0) {
+    const codes = new Set(workflowContract.violations.map((violation) => violation.code));
+    if (codes.has('missing_required_evidence')) {
+      push(
+        'attach_workflow_evidence',
+        'Attach workflow evidence before completion',
+        'Attach every required evidence label from the workflow contract before commit, push, PR, merge, release, or publish.',
+        'Deterministic workflows should not claim completion until the run contract is proven.'
+      );
+    }
+    if (codes.has('branch_outside_contract')) {
+      push(
+        'switch_to_contract_branch',
+        'Move to an allowed workflow branch',
+        'Switch to a branch allowed by the workflow contract or update the contract before retrying.',
+        'Workflow contracts define where repeatable agent runs are allowed to mutate state.'
+      );
+    }
+    if (codes.has('blocked_action')) {
+      push(
+        'remove_blocked_workflow_action',
+        'Remove blocked workflow action',
+        'Change the workflow step or request an explicit contract update before retrying this action.',
+        'The run contract blocks this action before execution.'
+      );
+    }
+  }
   if (workflowControl && workflowControl.mode && workflowControl.mode !== 'allow') {
     push(
       'add_environment_inspection',
@@ -1068,6 +1231,7 @@ function buildDecisionControl({
   protectedSurface,
   costControl,
   workflowControl,
+  workflowContract,
   actionProfile,
 }) {
   const reversibility = classifyReversibility({
@@ -1082,11 +1246,14 @@ function buildDecisionControl({
   const hasCostBlock = Boolean(costControl && costControl.mode === 'block');
   const hasWorkflowWarning = Boolean(workflowControl && workflowControl.mode === 'warn');
   const hasWorkflowBlock = Boolean(workflowControl && workflowControl.mode === 'block');
+  const hasContractWarning = Boolean(workflowContract && workflowContract.mode === 'warn');
+  const hasContractBlock = Boolean(workflowContract && workflowContract.mode === 'block');
   const requiresCheckpoint = decision === 'warn'
-    || (decision === 'allow' && (reversibility !== 'two_way_door' || hasOperationalBlockers || hasCostWarning || hasWorkflowWarning));
+    || (decision === 'allow' && (reversibility !== 'two_way_door' || hasOperationalBlockers || hasCostWarning || hasWorkflowWarning || hasContractWarning));
   const executionMode = decision === 'deny'
     || hasCostBlock
     || hasWorkflowBlock
+    || hasContractBlock
     ? 'blocked'
     : requiresCheckpoint
       ? 'checkpoint_required'
@@ -1110,7 +1277,7 @@ function buildDecisionControl({
     decisionOwner,
     reversibility,
     deliberation,
-    requiresHumanApproval: (executionMode === 'checkpoint_required' && decisionOwner !== 'agent') || hasCostBlock || hasWorkflowBlock,
+    requiresHumanApproval: (executionMode === 'checkpoint_required' && decisionOwner !== 'agent') || hasCostBlock || hasWorkflowBlock || hasContractBlock,
     recommendedAction: executionMode === 'blocked'
       ? 'halt'
       : executionMode === 'checkpoint_required'
@@ -1124,7 +1291,7 @@ function buildDecisionControl({
   };
 }
 
-function chooseDecision({ riskScore, integrity, memoryGuard, learnedPolicy, blastRadius, command, costControl, workflowControl, actionProfile }) {
+function chooseDecision({ riskScore, integrity, memoryGuard, learnedPolicy, blastRadius, command, costControl, workflowControl, workflowContract, actionProfile }) {
   const hasOperationalBlockers = Boolean(integrity && Array.isArray(integrity.blockers) && integrity.blockers.length > 0);
   if (costControl && costControl.mode === 'block') {
     return 'deny';
@@ -1132,6 +1299,9 @@ function chooseDecision({ riskScore, integrity, memoryGuard, learnedPolicy, blas
   if (workflowControl && workflowControl.mode === 'block') {
     return 'deny';
   }
+  if (workflowContract && workflowContract.mode === 'block') {
+    return 'deny';
+  }
   const destructiveBypass = /\bgit\s+push\b.*(?:--force|-f)\b/i.test(command) || /\bgh\s+pr\s+merge\b.*--admin\b/i.test(command);
   const learnedPrediction = learnedPolicy && learnedPolicy.enabled ? learnedPolicy.prediction : null;
   const learnedHardStop = Boolean(
@@ -1189,7 +1359,7 @@ function chooseDecision({ riskScore, integrity, memoryGuard, learnedPolicy, blas
   if (economicAction || (backgroundAgent && riskScore >= 0.3)) {
     return 'warn';
   }
-  if ((workflowControl && workflowControl.mode === 'warn') || (costControl && costControl.mode === 'warn') || riskScore >= 0.45 || (learnedWarning && riskScore >= 0.3) || (learnedRecall && riskScore >= 0.34)) {
+  if ((workflowContract && workflowContract.mode === 'warn') || (workflowControl && workflowControl.mode === 'warn') || (costControl && costControl.mode === 'warn') || riskScore >= 0.45 || (learnedWarning && riskScore >= 0.3) || (learnedRecall && riskScore >= 0.34)) {
     return 'warn';
   }
   return 'allow';
@@ -1243,6 +1413,15 @@ function evaluateWorkflowSentinel(toolName, toolInput = {}, options = {}) {
     requireVersionNotBehindBase: options.requireVersionNotBehindBase === true,
     branchGovernance: governanceState.branchGovernance,
   });
+  const workflowContract = evaluateWorkflowContract(
+    normalizedToolInput.workflowContract || options.workflowContract || governanceState.workflowContract,
+    {
+      command: normalizedToolInput.command || '',
+      currentBranch: integrity.currentBranch,
+      toolInput: normalizedToolInput,
+      options,
+    }
+  );
   const taskScopeViolation = buildTaskScopeViolation(governanceState.taskScope, affectedFiles);
   const protectedSurface = buildProtectedSurface(governanceState, affectedFiles);
   const protectedSurfaceForRisk = isProtectedApprovalRelevant(normalizedToolName, normalizedToolInput)
@@ -1290,6 +1469,7 @@ function evaluateWorkflowSentinel(toolName, toolInput = {}, options = {}) {
     protectedSurface: protectedSurfaceForRisk,
     costControl,
     workflowControl,
+    workflowContract,
     actionProfile,
   });
   const executionSurface = buildDockerSandboxPlan({
@@ -1316,6 +1496,7 @@ function evaluateWorkflowSentinel(toolName, toolInput = {}, options = {}) {
     command: normalizedToolInput.command || '',
     costControl,
     workflowControl,
+    workflowContract,
     actionProfile,
   });
   const evidence = buildEvidence({
@@ -1328,6 +1509,7 @@ function evaluateWorkflowSentinel(toolName, toolInput = {}, options = {}) {
     normalizedAction,
     costControl,
     workflowControl,
+    workflowContract,
     actionProfile,
   });
   const remediations = buildRemediations({
@@ -1340,6 +1522,7 @@ function evaluateWorkflowSentinel(toolName, toolInput = {}, options = {}) {
     executionSurface,
     costControl,
     workflowControl,
+    workflowContract,
     actionProfile,
   });
   const summary = decision === 'allow'
@@ -1353,6 +1536,7 @@ function evaluateWorkflowSentinel(toolName, toolInput = {}, options = {}) {
     normalizedAction,
     costControl,
     workflowControl,
+    workflowContract,
     decision,
     riskScore: risk.score,
     band: risk.band,
@@ -1388,6 +1572,7 @@ function evaluateWorkflowSentinel(toolName, toolInput = {}, options = {}) {
     protectedSurface: protectedSurfaceForRisk,
     costControl,
     workflowControl,
+    workflowContract,
     actionProfile,
   });
   report.reasoning = buildReasoning(report);