thumbgate 1.25.2 → 1.26.1

package/scripts/operational-dashboard.js

@@ -0,0 +1,160 @@
+'use strict';
+
+const { resolveAnalyticsWindow } = require('./analytics-window');
+const { getBillingSummaryLive } = require('./billing');
+const { generateDashboard } = require('./dashboard');
+const { getFeedbackPaths } = require('./feedback-loop');
+const { resolveHostedBillingConfig } = require('./hosted-config');
+const { loadOperatorConfig } = require('./operational-summary');
+
+function normalizeText(value) {
+  if (value === undefined || value === null) return null;
+  const text = String(value).trim();
+  return text || null;
+}
+
+function shouldPreferHostedDashboard() {
+  return String(process.env.THUMBGATE_METRICS_SOURCE || '').trim().toLowerCase() !== 'local';
+}
+
+function resolveHostedDashboardConfig() {
+  const runtimeConfig = resolveHostedBillingConfig();
+  const operatorConfig = loadOperatorConfig();
+  // Match operational-summary's key priority chain so north-star and cfo
+  // authenticate against the same hosted deployment consistently. Prior to
+  // this change, north-star only read THUMBGATE_API_KEY, silently 401'ing
+  // on machines configured via operator.json or THUMBGATE_OPERATOR_KEY.
+  const apiKey = normalizeText(process.env.THUMBGATE_OPERATOR_KEY)
+    || operatorConfig.operatorKey
+    || normalizeText(process.env.THUMBGATE_API_KEY);
+  const apiBaseUrl = normalizeText(process.env.THUMBGATE_BILLING_API_BASE_URL)
+    || operatorConfig.baseUrl
+    || runtimeConfig.billingApiBaseUrl;
+  return {
+    apiBaseUrl,
+    apiKey,
+  };
+}
+
+async function buildOperationalDashboard(options = {}) {
+  const analyticsWindow = resolveAnalyticsWindow(options);
+  const feedbackDir = options.feedbackDir || getFeedbackPaths().FEEDBACK_DIR;
+  const billingSummary = await getBillingSummaryLive(analyticsWindow);
+
+  return generateDashboard(feedbackDir, {
+    analyticsWindow,
+    billingSummary,
+    billingSource: 'live',
+    billingFallbackReason: null,
+  });
+}
+
+async function fetchHostedDashboard(options = {}, config = resolveHostedDashboardConfig()) {
+  const analyticsWindow = resolveAnalyticsWindow(options);
+  if (!shouldPreferHostedDashboard()) {
+    const err = new Error('Hosted operational dashboard is disabled.');
+    err.code = 'hosted_dashboard_disabled';
+    throw err;
+  }
+  if (!config.apiBaseUrl || !config.apiKey) {
+    const err = new Error('Hosted operational dashboard is not configured.');
+    err.code = 'hosted_dashboard_unconfigured';
+    throw err;
+  }
+
+  const requestUrl = new URL('/v1/dashboard', config.apiBaseUrl);
+  requestUrl.searchParams.set('window', analyticsWindow.window);
+  requestUrl.searchParams.set('timezone', analyticsWindow.timeZone);
+  requestUrl.searchParams.set('now', analyticsWindow.now);
+
+  const response = await fetch(requestUrl, {
+    method: 'GET',
+    headers: {
+      authorization: `Bearer ${config.apiKey}`,
+      accept: 'application/json',
+    },
+  });
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '');
+    const err = new Error(`Hosted operational dashboard request failed (${response.status}): ${detail || 'unknown error'}`);
+    err.code = 'hosted_dashboard_http_error';
+    err.status = response.status;
+    throw err;
+  }
+
+  return response.json();
+}
+
+async function getOperationalDashboard(options = {}) {
+  const analyticsWindow = resolveAnalyticsWindow(options);
+  try {
+    const data = await fetchHostedDashboard(analyticsWindow);
+    return {
+      source: 'hosted',
+      data,
+      fallbackReason: null,
+      hostedStatus: 200,
+    };
+  } catch (err) {
+    const reason = err && err.message ? err.message : 'hosted_dashboard_unavailable';
+    const status = err && typeof err.status === 'number' ? err.status : null;
+    const code = err && err.code ? err.code : null;
+
+    // Hosted deliberately disabled or never configured — local fallback is
+    // intentional, not a degraded state. Tag as plain 'local'.
+    if (code === 'hosted_dashboard_disabled' || code === 'hosted_dashboard_unconfigured') {
+      return {
+        source: 'local',
+        data: await buildOperationalDashboard(analyticsWindow),
+        fallbackReason: reason,
+        hostedStatus: null,
+      };
+    }
+
+    // Mirror operational-summary: auth failure is the dangerous case. A
+    // dashboard that silently shows $0 revenue (from the local ledger) when
+    // Stripe actually has paid customers is a lie the operator acts on.
+    // Refuse to guess — surface an actionable error.
+    if (status === 401 || status === 403) {
+      const authErr = new Error(
+        `Hosted operational dashboard rejected credentials (HTTP ${status}). ` +
+        `The operator key on this machine does not match the one on the ` +
+        `hosted deployment. Fix: set THUMBGATE_OPERATOR_KEY in this shell, ` +
+        `or update the operatorKey field in ~/.config/thumbgate/operator.json, ` +
+        `to match Railway's THUMBGATE_OPERATOR_KEY. ` +
+        `Running north-star without hosted auth would report local-only ` +
+        `data as ground truth, which may not reflect actual Stripe revenue. ` +
+        `Original response: ${reason}`
+      );
+      authErr.code = 'hosted_dashboard_unauthorized';
+      authErr.status = status;
+      throw authErr;
+    }
+
+    // Non-auth failure — local fallback is still useful for dev workflows,
+    // but tag the source so downstream renderers do not mistake it for
+    // verified hosted truth.
+    //
+    // Log only the status code (trusted) — the full reason contains upstream
+    // response text and is only returned structurally via fallbackReason.
+    console.warn(
+      `[operational-dashboard] Hosted dashboard unreachable (status=${status ?? 'network'}); ` +
+      `falling back to LOCAL-UNVERIFIED state. Numbers below may not reflect actual Stripe revenue.`
+    );
+    return {
+      source: 'local-unverified',
+      data: await buildOperationalDashboard(analyticsWindow),
+      fallbackReason: reason,
+      hostedStatus: status,
+    };
+  }
+}
+
+module.exports = {
+  buildOperationalDashboard,
+  fetchHostedDashboard,
+  getOperationalDashboard,
+  resolveHostedDashboardConfig,
+  shouldPreferHostedDashboard,
+};

package/scripts/plan-gate.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Plan Gate — implementing the CodeRabbit "Planning-First" pattern.
+ *
+ * 1. (Static) Validates structured 'PLAN.md' / 'PRD' content (used in loop-closure).
+ * 2. (Dynamic) Intercepts high-risk tool calls during agent execution.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RISK_TOOLS = ['Bash', 'Write', 'Edit', 'Deploy'];
+
+// ---------------------------------------------------------------------------
+// Gate validators (Legacy / Loop Closure)
+// ---------------------------------------------------------------------------
+
+function countTableRows(content, sectionHeading) {
+  const sectionRegex = new RegExp(
+    `#+\\s*${sectionHeading}[^\\n]*\\n([\\s\\S]*?)(?=\\n#+\\s|$)`,
+  );
+  const match = content.match(sectionRegex);
+  if (!match) return 0;
+
+  const lines = match[1].split('\n').filter((l) => l.trim().startsWith('|'));
+  // Subtract header row and separator row
+  const dataRows = lines.filter(
+    (l) => !/^\|\s*-+/.test(l.trim()) && !/^\|\s*:?-+/.test(l.trim()),
+  );
+  // First row is the header
+  return Math.max(0, dataRows.length - 1);
+}
+
+function countContracts(content) {
+  const sectionRegex = /#+\s*Contracts[^\n]*\n([\s\S]*?)(?=\n#+\s|$)/;
+  const match = content.match(sectionRegex);
+  if (!match) return 0;
+
+  const section = match[1];
+  // Find code blocks and look for interface/type keywords inside them
+  const codeBlockRegex = /```[\s\S]*?```/g;
+  let count = 0;
+  let blockMatch;
+  while ((blockMatch = codeBlockRegex.exec(section)) !== null) {
+    const block = blockMatch[0];
+    const interfaceMatches = block.match(/\b(interface|type)\s+\w+/g);
+    if (interfaceMatches) count += interfaceMatches.length;
+  }
+  return count;
+}
+
+function countValidationScenarios(content) {
+  const sectionRegex =
+    /#+\s*Validation\s+Checklist[^\n]*\n([\s\S]*?)(?=\n#+\s|$)/;
+  const match = content.match(sectionRegex);
+  if (!match) return 0;
+
+  const lines = match[1].split('\n');
+  return lines.filter((l) => /^\s*-\s*\[\s*\]/.test(l)).length;
+}
+
+function getStatus(content) {
+  const match = content.match(/#+\s*Status[^\n]*\n\s*(\S+)/);
+  return match ? match[1].trim() : null;
+}
+
+function validatePlan(content) {
+  const questionCount = countTableRows(content, 'Clarifying Questions Resolved');
+  const contractCount = countContracts(content);
+  const scenarioCount = countValidationScenarios(content);
+  const status = getStatus(content);
+
+  const gates = [
+    {
+      name: 'Clarifying Questions',
+      pass: questionCount >= 3,
+      detail: `${questionCount} questions resolved`,
+    },
+    {
+      name: 'Contracts Defined',
+      pass: contractCount >= 1,
+      detail: `${contractCount} interface${contractCount !== 1 ? 's' : ''} found`,
+    },
+    {
+      name: 'Validation Checklist',
+      pass: scenarioCount >= 2,
+      detail: `${scenarioCount} scenarios defined`,
+    },
+    {
+      name: 'Status',
+      pass: status !== 'COMPLETE',
+      detail:
+        status === 'COMPLETE'
+          ? 'COMPLETE (already finished — cannot re-approve)'
+          : `${status || 'UNKNOWN'} (not COMPLETE)`,
+    },
+  ];
+
+  const allPass = gates.every((g) => g.pass);
+  return { gates, allPass };
+}
+
+function formatReport(result) {
+  const lines = result.gates.map(
+    (g) => `${g.pass ? '✅' : '❌'} ${g.name}: ${g.detail}`,
+  );
+  lines.push('');
+  lines.push(
+    result.allPass
+      ? 'RESULT: PASS — all gates satisfied'
+      : 'RESULT: BLOCKED — resolve issues above before spawning agents',
+  );
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Dynamic Gating (CodeRabbit Orchestration Pattern)
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluates the planning state for the current tool call.
+ */
+function evaluatePlanGate(toolName, toolInput, options = {}) {
+  if (!RISK_TOOLS.includes(toolName)) return null;
+
+  const projectRoot = options.projectRoot || process.cwd();
+  const planPath = path.join(projectRoot, 'PLAN.md');
+
+  // Tier 1: Existence Check
+  if (!fs.existsSync(planPath)) {
+    return {
+      decision: 'warn',
+      gate: 'plan-gate-missing',
+      message: '⚠️ THUMBGATE: High-risk tool call without a PLAN.md. Please create a plan documenting your intent and assumptions.',
+      severity: 'high'
+    };
+  }
+
+  // Tier 2: Alignment Check (Simple)
+  const planContent = fs.readFileSync(planPath, 'utf8');
+  const action = toolName === 'Bash' ? toolInput.command : toolInput.filePath;
+  
+  if (action && !planContent.toLowerCase().includes(path.basename(action).toLowerCase())) {
+    return {
+      decision: 'warn',
+      gate: 'plan-gate-drift',
+      message: `⚠️ THUMBGATE: Strategic Drift detected. The action "${action}" is not mentioned in your PLAN.md.`,
+      severity: 'medium'
+    };
+  }
+
+  // Tier 3: Implicit Assumption Extraction
+  const assumptions = extractAssumptions(planContent);
+  if (assumptions.length > 0) {
+    return {
+      decision: 'warn',
+      gate: 'plan-gate-assumptions',
+      message: '🔍 THUMBGATE: Explicitly verify these implicit assumptions before proceeding:\n- ' + assumptions.join('\n- '),
+      severity: 'medium'
+    };
+  }
+
+  // Tier 4: Self-Critique / Risk Mitigation Check (Tip #8)
+  const hasCritique = /(?:critique|self-critique|risk|mitigation|alternative|flaw|weakness|pitfall)/i.test(planContent);
+  if (!hasCritique) {
+    return {
+      decision: 'warn',
+      gate: 'plan-gate-critique-missing',
+      message: '🧐 THUMBGATE: No Self-Critique/Risk Analysis detected in your PLAN.md. Please add a "Critique", "Risks", or "Mitigations" section to evaluate potential flaws in this plan before executing high-risk tools.',
+      severity: 'medium'
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Scans plan content for "Assumes" or "Implicit" keywords.
+ */
+function extractAssumptions(content) {
+  const lines = content.split('\n');
+  const assumptions = [];
+  const regex = /(?:assume|assumption|implicit|pre-requisite|depends on)s?[:\-]?\s*(.*)/i;
+  
+  for (const line of lines) {
+    const match = line.match(regex);
+    if (match && match[1].trim()) {
+      assumptions.push(match[1].trim());
+    }
+  }
+  return assumptions.slice(0, 5);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function run() {
+  const args = process.argv.slice(2);
+  const jsonFlag = args.includes('--json');
+  const filePath = args.find((a) => a !== '--json');
+
+  if (!filePath) {
+    console.error('Usage: node scripts/plan-gate.js <plan-file.md> [--json]');
+    process.exit(1);
+  }
+
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    console.error(`File not found: ${resolved}`);
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(resolved, 'utf-8');
+  const result = validatePlan(content);
+
+  if (jsonFlag) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatReport(result));
+  }
+
+  process.exit(result.allPass ? 0 : 1);
+}
+
+// Export for testing
+module.exports = {
+  validatePlan,
+  formatReport,
+  countTableRows,
+  countContracts,
+  countValidationScenarios,
+  getStatus,
+  evaluatePlanGate,
+  extractAssumptions,
+};
+
+// Run only when executed directly
+if (require.main === module) {
+  run();
+}

package/scripts/repeat-metric.js

@@ -0,0 +1,121 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// repeat-metric — first-class "repeat-attempts blocked before execution" metric
+//
+// This module exposes data ThumbGate already collects in gate-stats state. It
+// does NOT write to disk; it is a pure function over gates-engine.loadStats().
+//
+// The headline number is stats.recurringBlocks — incremented by recordStat()
+// in gates-engine.js every time the SAME gateId fires twice within one session
+// bucket. That is exactly "a pre-action gate fire that stopped a tool call the
+// agent had already been blocked on", i.e. a repeat attempt prevented before it
+// could round-trip and execute.
+// ---------------------------------------------------------------------------
+
+const gatesEngine = require('./gates-engine');
+
+/**
+ * Derive a per-gate { firstBlocks, repeatBlocks } split from the raw stats.
+ *
+ * recordStat() records, per session bucket, which gates have fired
+ * (stats.sessionFiredGates[sessionKey][gateId] === true). The FIRST fire of a
+ * gate in a bucket marks the flag; every subsequent fire in that same bucket
+ * increments stats.recurringBlocks. So for each gate:
+ *   firstBlocks  = number of distinct session buckets the gate fired in
+ *   repeatBlocks = (total block+warn events for the gate) - firstBlocks
+ *
+ * total block+warn events come from stats.byGate[id] (blocked + warned), which
+ * recordStat() also maintains. repeatBlocks is clamped to >= 0 to stay robust
+ * against partially-written / legacy state.
+ *
+ * @param {object} stats raw object returned by gates-engine.loadStats()
+ * @returns {Object<string,{firstBlocks:number, repeatBlocks:number}>}
+ */
+function computeByGateSplit(stats) {
+  const byGate = {};
+  const sessionFiredGates = (stats && stats.sessionFiredGates) || {};
+  const rawByGate = (stats && stats.byGate) || {};
+
+  // Count distinct session buckets each gate fired in => firstBlocks.
+  const firstBlocksByGate = {};
+  for (const sessionKey of Object.keys(sessionFiredGates)) {
+    const fired = sessionFiredGates[sessionKey] || {};
+    for (const gateId of Object.keys(fired)) {
+      if (fired[gateId]) {
+        firstBlocksByGate[gateId] = (firstBlocksByGate[gateId] || 0) + 1;
+      }
+    }
+  }
+
+  // Union of every gate id we know about from either source.
+  const gateIds = new Set([
+    ...Object.keys(rawByGate),
+    ...Object.keys(firstBlocksByGate),
+  ]);
+
+  for (const gateId of gateIds) {
+    const gateStat = rawByGate[gateId] || {};
+    const totalFires = (gateStat.blocked || 0) + (gateStat.warned || 0);
+    const firstBlocks = firstBlocksByGate[gateId] || 0;
+    // Repeat fires are total fires beyond the first fire per session bucket.
+    const repeatBlocks = Math.max(0, totalFires - firstBlocks);
+    byGate[gateId] = { firstBlocks, repeatBlocks };
+  }
+
+  return byGate;
+}
+
+/**
+ * Compute the repeat-attempts-blocked-before-execution metric.
+ *
+ * Pure read of gates-engine.loadStats(); no disk writes.
+ *
+ * @returns {{
+ *   repeatBlocksBeforeExecution: number,
+ *   recurringBlocks: number,
+ *   totalBlocked: number,
+ *   byGate: Object<string,{firstBlocks:number, repeatBlocks:number}>
+ * }}
+ */
+function computeRepeatMetric() {
+  let stats;
+  try {
+    stats = gatesEngine.loadStats() || {};
+  } catch (_) {
+    stats = {};
+  }
+
+  const recurringBlocks = Number(stats.recurringBlocks || 0);
+  const totalBlocked = Number(stats.blocked || 0);
+
+  return {
+    // Headline: a pre-action block that stopped a tool call the agent had
+    // already been blocked on this session.
+    repeatBlocksBeforeExecution: recurringBlocks,
+    recurringBlocks,
+    totalBlocked,
+    byGate: computeByGateSplit(stats),
+  };
+}
+
+/**
+ * Add a `repeat` sub-key to a gate-stats object WITHOUT mutating the original.
+ *
+ * Takes the object returned by gate-stats.calculateStats() or
+ * dashboard.computeGateStats() and returns a shallow copy with the repeat
+ * metric attached. The caller's file does not need to import any internals.
+ *
+ * @param {object} gateStatsObject
+ * @returns {object} copy of gateStatsObject with `.repeat`
+ */
+function mergeRepeatMetricIntoGateStats(gateStatsObject) {
+  const base = gateStatsObject && typeof gateStatsObject === 'object' ? gateStatsObject : {};
+  return Object.assign({}, base, { repeat: computeRepeatMetric() });
+}
+
+module.exports = {
+  computeRepeatMetric,
+  mergeRepeatMetricIntoGateStats,
+  computeByGateSplit,
+};

package/scripts/silent-failure-cluster.js

@@ -4,7 +4,14 @@
 /**
  * Silent-Failure Clustering — Unsupervised candidate source for the meta-agent loop
  *
- * Off by default. Enabled with: THUMBGATE_SILENT_FAILURE_CLUSTERING=1
+ * Default-ON since 2026-05-21. Opt-out with: THUMBGATE_SILENT_FAILURE_CLUSTERING=0
+ * (or set NODE_ENV=test to skip in test runs). Was opt-in for the initial
+ * landing of PR #2285; flipped to default-on because the entire point is to
+ * cover the case where users never give thumbs-down — keeping it opt-in
+ * means lazy users (the ones who need it most) never benefit. Bounded risk:
+ * candidates still flow through meta-agent-loop's existing fp-rate eval, so
+ * a noisy cluster can't auto-promote to a real gate without passing the
+ * same precision/recall thresholds as LLM-generated candidates.
  *
  * Problem: ThumbGate's HITL loop only learns from explicit thumbs-down. Tool calls
  * that fail without user feedback (exit_code != 0, regex-matched error in output,
@@ -460,9 +467,20 @@ function generateSilentFailureCandidates(opts = {}) {
 // CLI
 // ---------------------------------------------------------------------------
 
+/**
+ * Resolve the enabled state. Default ON. Explicit "0" or "false" opts out;
+ * NODE_ENV=test also opts out to keep test runs deterministic.
+ */
+function isSilentFailureClusteringEnabled(env = process.env) {
+  if (env.NODE_ENV === 'test') return false;
+  const raw = (env.THUMBGATE_SILENT_FAILURE_CLUSTERING || '').toLowerCase();
+  if (raw === '0' || raw === 'false' || raw === 'off' || raw === 'no') return false;
+  return true;
+}
+
 async function main() {
-  if (process.env.THUMBGATE_SILENT_FAILURE_CLUSTERING !== '1') {
-    process.stdout.write('silent-failure-cluster: disabled (set THUMBGATE_SILENT_FAILURE_CLUSTERING=1 to enable)\n');
+  if (!isSilentFailureClusteringEnabled()) {
+    process.stdout.write('silent-failure-cluster: disabled (THUMBGATE_SILENT_FAILURE_CLUSTERING=0 or NODE_ENV=test)\n');
     return;
   }
 
@@ -492,6 +510,7 @@ if (require.main === module) {
 
 module.exports = {
   generateSilentFailureCandidates,
+  isSilentFailureClusteringEnabled,
   // exported for testing
   redactSecrets,
   normalizePaths,

package/scripts/thompson-sampling.js

@@ -301,6 +301,24 @@ function getCalibration(model) {
 // Posterior Sampling
 // ---------------------------------------------------------------------------
 
+/**
+ * Return the Beta posterior parameters after applying Thompson temperature
+ * scaling. The posterior mean is preserved while precision changes:
+ * lower temperatures sharpen the posterior, higher temperatures flatten it.
+ *
+ * @param {Object} params - Category posterior parameters
+ * @param {number} temperature - Scaling factor (default 1.0)
+ * @returns {{ alpha: number, beta: number }}
+ */
+function getTemperatureScaledPosteriorParams(params, temperature = 1.0) {
+  const T = Math.max(0.01, Number(temperature) || 1.0);
+  const invT = 1.0 / T;
+  return {
+    alpha: Math.max(params.alpha * invT, 0.01),
+    beta: Math.max(params.beta * invT, 0.01),
+  };
+}
+
 /**
  * Draw one sample from the Beta posterior for each category.
  * Supports temperature scaling to adjust exploitation vs exploration.
@@ -318,13 +336,9 @@ function getCalibration(model) {
  */
 function samplePosteriors(model, temperature = 1.0) {
   const samples = {};
-  const T = Math.max(0.01, Number(temperature) || 1.0);
-  const invT = 1.0 / T;
 
   for (const [cat, params] of Object.entries(model.categories || {})) {
-    // Scale precision by inverse temperature
-    const alpha = Math.max(params.alpha * invT, 0.01);
-    const beta = Math.max(params.beta * invT, 0.01);
+    const { alpha, beta } = getTemperatureScaledPosteriorParams(params, temperature);
     samples[cat] = betaSample(alpha, beta);
   }
   return samples;
@@ -457,6 +471,7 @@ module.exports = {
   getReliability,
   isCalibrated,
   getCalibration,
+  getTemperatureScaledPosteriorParams,
   samplePosteriors,
   argmaxPosteriors,
   pickBestCategory,

package/scripts/tool-registry.js

@@ -895,6 +895,56 @@ const TOOLS = [
       },
     },
   }),
+  destructiveTool({
+    name: 'detect_noop',
+    title: 'Detect No-op Action',
+    description: 'Detect whether a tool call was a no-op (state unchanged) or identical to a prior attempt in the session — a cheap repeat-loop signal. Records the action attempt state for repeat detection.',
+    inputSchema: {
+      type: 'object',
+      required: ['actionId'],
+      properties: {
+        actionId: { type: 'string', description: 'Stable identifier for the action being checked (e.g. the file path or command being attempted)' },
+        kind: { type: 'string', enum: ['file', 'command'], description: 'Action kind: file edit/write or command execution' },
+        filePath: { type: 'string', description: 'Path of the file the action targets (file kind)' },
+        beforeContent: { type: 'string', description: 'File content before the action (file kind)' },
+        afterContent: { type: 'string', description: 'File content after the action (file kind)' },
+        exitCode: { type: 'number', description: 'Command exit code (command kind)' },
+        stdout: { type: 'string', description: 'Command stdout (command kind)' },
+        stderr: { type: 'string', description: 'Command stderr (command kind)' },
+        sessionId: { type: 'string', description: 'Optional session id used to scope repeat-attempt detection' },
+      },
+    },
+  }),
+  destructiveTool({
+    name: 'record_action_receipt',
+    title: 'Record Action Receipt',
+    description: 'Pair a tracked tool call with its outcome (diff, exit code, test result) so a promoted lesson encodes "this action -> this outcome", not just a thumbs signal. Appends to the action-receipts log.',
+    inputSchema: {
+      type: 'object',
+      required: ['actionId'],
+      properties: {
+        actionId: { type: 'string', description: 'Identifier of the tracked action this receipt pairs with' },
+        toolName: { type: 'string', description: 'Name of the tool that was invoked' },
+        toolInput: { type: 'object', description: 'Structured input the tool was called with' },
+        diff: { type: 'string', description: 'Optional unified diff or change summary produced by the action' },
+        exitCode: { type: 'number', description: 'Optional command exit code outcome' },
+        testOutcome: { type: 'string', description: 'Optional test outcome (e.g. passed, failed, 12/12)' },
+        stateHash: { type: 'string', description: 'Optional post-action state hash (from detect_noop)' },
+      },
+    },
+  }),
+  readOnlyTool({
+    name: 'get_action_receipts',
+    title: 'Get Action Receipts',
+    description: 'Read outcome-paired action receipts. Returns the receipt for a specific actionId, or the most recent receipts when no actionId is given.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        actionId: { type: 'string', description: 'Optional action id to fetch the matching receipt for' },
+        limit: { type: 'number', description: 'Max number of recent receipts to return when no actionId is given (default 20)' },
+      },
+    },
+  }),
   readOnlyTool({
     name: 'verify_claim',
     description: 'Check whether a claim has enough tracked evidence before the agent asserts it.',