thumbgate 1.27.18 → 1.27.19

package/scripts/gates-engine.js

@@ -3,11 +3,12 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const crypto = require('crypto');
-const { execSync, execFileSync } = require('child_process');
+const { execFileSync } = require('child_process');
 const { loadOptionalModule } = require('./private-core-boundary');
 
-const { isProTier, FREE_TIER_MAX_GATES } = require('./rate-limiter');
+const { isProTier, isInTrialPeriod, FREE_TIER_MAX_GATES, FREE_TIER_DAILY_BLOCKS, todayKey } = require('./rate-limiter');
 const {
   DEFAULT_BASE_BRANCH,
   evaluateOperationalIntegrity,
@@ -19,6 +20,10 @@ const {
   recordDecisionEvaluation,
   recordDecisionOutcome,
 } = require('./decision-journal');
+const {
+  actionFingerprint,
+  sanitizeFeedbackText,
+} = require('./feedback-sanitizer');
 
 /**
  * Computes the SHA-256 hash of an executable binary to prevent path-based bypasses.
@@ -30,10 +35,12 @@ function computeExecutableHash(command) {
     const firstWord = command.trim().split(/\s+/)[0];
     if (!firstWord) return null;
 
-    // Resolve absolute path using 'which'
+    // Resolve absolute path using 'which'. Use execFileSync (no shell) and pass
+    // firstWord as an argv element, never interpolated into a command string, so
+    // a hostile `command` value cannot inject shell metacharacters here.
     let fullPath;
     try {
-      fullPath = execSync(`which ${firstWord}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      fullPath = execFileSync('which', [firstWord], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
     } catch (e) {
       // If 'which' fails, it might be an absolute path or a non-existent command
       fullPath = path.isAbsolute(firstWord) ? firstWord : null;
@@ -51,21 +58,44 @@ const {
   scanHookInput,
   buildSafeSummary,
   redactText,
+  isSafeSecretStorageWrite,
+  SAFE_SECRET_STORAGE_DIRS,
 } = require('./secret-scanner');
 const {
   evaluateSecurityScan,
 } = require('./security-scanner');
+const { evaluatePlanGate } = require('./plan-gate');
+const { getTrajectoryScore } = require('./trajectory-scorer');
+const { evaluateSequenceState } = loadOptionalModule('./sequence-guard', () => ({
+  evaluateSequenceState: () => null,
+}));
 const { getAutoGatesPath } = require('./auto-promote-gates');
 const { recordAuditEvent, auditToFeedback } = require('./audit-trail');
 
 const DEFAULT_CONFIG_PATH = path.join(__dirname, '..', 'config', 'gates', 'default.json');
 const DEFAULT_CLAIM_GATES_PATH = path.join(__dirname, '..', 'config', 'gates', 'claim-verification.json');
-const STATE_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'gate-state.json');
-const CONSTRAINTS_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'session-constraints.json');
-const STATS_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'gate-stats.json');
-const SESSION_ACTIONS_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'session-actions.json');
-const CUSTOM_CLAIM_GATES_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'claim-verification.json');
-const GOVERNANCE_STATE_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'governance-state.json');
+
+function resolveThumbgateStateDir() {
+  if (process.env.THUMBGATE_STATE_DIR) return process.env.THUMBGATE_STATE_DIR;
+
+  if (process.env.XDG_STATE_HOME) {
+    return path.join(process.env.XDG_STATE_HOME, 'thumbgate');
+  }
+
+  if (process.env.CODEX_SANDBOX) {
+    return path.join(os.tmpdir(), 'thumbgate');
+  }
+
+  return path.join(process.env.HOME || os.tmpdir(), '.thumbgate');
+}
+
+const STATE_DIR = resolveThumbgateStateDir();
+const STATE_PATH = path.join(STATE_DIR, 'gate-state.json');
+const CONSTRAINTS_PATH = path.join(STATE_DIR, 'session-constraints.json');
+const STATS_PATH = path.join(STATE_DIR, 'gate-stats.json');
+const SESSION_ACTIONS_PATH = path.join(STATE_DIR, 'session-actions.json');
+const CUSTOM_CLAIM_GATES_PATH = path.join(STATE_DIR, 'claim-verification.json');
+const GOVERNANCE_STATE_PATH = path.join(STATE_DIR, 'governance-state.json');
 const TTL_MS = 5 * 60 * 1000; // 5 minutes
 const SESSION_ACTION_TTL_MS = 60 * 60 * 1000; // 1 hour
 const PROTECTED_APPROVAL_TTL_MS = 60 * 60 * 1000; // 1 hour
@@ -85,12 +115,127 @@ const DEFAULT_PROTECTED_FILE_GLOBS = [
 const EDIT_LIKE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']);
 const HIGH_RISK_BASH_PATTERN = /\b(?:git\s+(?:add|commit|push)|gh\s+pr\s+(?:create|merge)|npm\s+publish|yarn\s+publish|pnpm\s+publish|rm\s+-rf)\b/i;
 const REMOTE_SIDE_EFFECT_BASH_PATTERN = /\b(?:git\s+push\b|gh\s+pr\s+(?:create|merge|close|reopen|ready|edit)\b|gh\s+release\s+(?:create|delete|edit|upload)\b|npm\s+publish\b|yarn\s+publish\b|pnpm\s+publish\b)\b/i;
+const MAX_COMMAND_SCAN_CHARS = 20000;
 const BOOSTED_RISK_BLOCK_SCORE = 0.8;
 const BOOSTED_RISK_MIN_EXAMPLES = 3;
 const PR_THREAD_RESOLUTION_ACTION = 'pr_thread_resolution_verified_after_commit';
+const HELPER_BYPASS_ACTION = 'helper_script_modified';
+const KNOWLEDGE_ENTROPY_THRESHOLD = 0.7;
+const KNOWLEDGE_CONFLICT_STRICT_BASH_PATTERN = /\b(?:git\s+push\b|gh\s+pr\s+merge\b|gh\s+release\s+(?:create|delete|edit|upload)\b|(?:npm|yarn|pnpm)\s+publish\b|rm\s+-rf\b|git\s+reset\s+--hard\b|git\s+clean\s+-f[a-z]*|railway\s+(?:deploy|up)\b|gcloud\s+(?:run\s+deploy|app\s+deploy)\b|firebase\s+deploy\b|vercel\s+--prod\b|kubectl\s+(?:apply|delete)\b|terraform\s+(?:apply|destroy)\b)\b/i;
+const HELPER_SCRIPT_FILE_PATTERN = /(?:^|\/)(?:scripts|bin|tools|tasks|\.githooks|\.github\/workflows)\/|(?:^|\/)(?:package\.json|Makefile|justfile|Taskfile\.ya?ml)$|\.(?:sh|bash|zsh|fish|js|mjs|cjs|ts|tsx|py|rb|pl|ps1|yml|yaml)$/i;
+const PACKAGE_RUN_PATTERN = /\b(?:npm|yarn|pnpm)\s+run\s+([:@./\w-]+)\b/i;
+const HELPER_EXEC_PATTERN = /(?:^|[;&|]\s*|\b(?:bash|sh|zsh|node|python3?|ruby|perl|tsx|ts-node)\s+)(?:(?:\.?\.?\/)?(?:scripts|bin|tools|tasks|tmp|build|dist|\.tmp|\.cache)\/[^\s;&|]+|\.\/[^\s;&|]+\.(?:sh|bash|zsh|js|mjs|cjs|ts|py|rb|pl|ps1))\b/i;
+const HELPER_WRITE_PATTERN = /\b(?:cat|printf|echo|tee|npm\s+pkg\s+set|jq|node\s+-e|python3?\s+-c)\b[\s\S]{0,300}(?:>|--field|scripts\.|package\.json|(?:scripts|bin|tools|tasks|tmp|build|dist|\.tmp|\.cache)\/[^\s;&|]+|\.(?:sh|js|mjs|cjs|ts|py|rb|pl|ps1))\b/i;
+const NETWORK_OR_PROCESS_BOUNDARY_PATTERN = /\b(?:curl|wget|nc|ncat|socat|ssh|scp|rsync|ftp|python3?\s+-m\s+http\.server|node\s+-e|python3?\s+-c|perl\s+-e|ruby\s+-e|bash\s+-c|sh\s+-c|osascript|open)\b/i;
+const DOWNLOAD_EXEC_CHAIN_PATTERN = /\b(?:curl|wget)\b[\s\S]{0,400}(?:\|\s*(?:bash|sh|zsh)|&&[\s\S]{0,200}\bchmod\s+\+x\b[\s\S]{0,200}&&[\s\S]{0,120}(?:\.\/|bash|sh|node|python3?))/i;
+const DESTRUCTIVE_OR_PRIVILEGE_BOUNDARY_PATTERN = /\b(?:rm\s+-rf|chmod\s+(?:\+x|777)|chown\b|sudo\b|dd\s+if=|mkfs|git\s+reset\s+--hard|git\s+clean\s+-f[a-z]*|kubectl\s+(?:apply|delete)|terraform\s+(?:apply|destroy)|railway\s+(?:deploy|up)|gcloud\s+(?:run\s+deploy|app\s+deploy)|vercel\s+--prod|firebase\s+deploy)\b/i;
+
+// ---------------------------------------------------------------------------
+// Enforcement posture (CEO decision 2026-06-04): warn-by-default.
+// The firewall ALWAYS fires and logs every decision, but most gates WARN rather
+// than hard-block — only TRULY CATASTROPHIC, irreversible actions hard-block:
+//   - secret exfiltration (handled on its own deny path; never downgraded)
+//   - security-vulnerability / supply-chain denies (own deny path; not downgraded)
+//   - irreversibly destructive filesystem commands (rm -rf class, mkfs, dd to disk,
+//     fork bomb) — kept as hard deny via DESTRUCTIVE_FS_PATTERN below.
+// Everything else (memory-high-risk, workflow-sequence, off-scope, git push, deploy,
+// approval gates) downgrades deny/approve -> warn so legitimate work is never blocked.
+// Opt back into full hard enforcement with THUMBGATE_STRICT_ENFORCEMENT=1.
+// Enforcement posture (CEO decision 2026-06-04): WARN + AUDIT by default.
+// The firewall fires and LOGS every decision, but downgrades deny/approve -> warn so
+// legitimate work is never hard-blocked. We deliberately do NOT try to hard-block
+// arbitrary destructive commands here: a regex "catastrophic floor" is unwinnable
+// (sudo / bash -c / find -exec / eval / base64|sh all evade it) and gives false confidence.
+// HARD enforcement is an explicit opt-in via THUMBGATE_STRICT_ENFORCEMENT=1, which keeps
+// the engine's FULL gate set (its high-risk-command gates catch prefixed/obfuscated forms
+// far better than any single regex). Secret exfiltration and the security-vulnerability
+// scan hard-deny on their OWN paths before this runs, so irreversible data-leak / supply
+// chain risks stay blocked regardless of posture.
+function applyEnforcementPosture(result) {
+  if (!result || (result.decision !== 'deny' && result.decision !== 'approve')) return result;
+  // Full hard enforcement opt-in: keep every deny.
+  if (process.env.THUMBGATE_STRICT_ENFORCEMENT === '1') return result;
+  // Honor the explicit strict-knowledge-conflict opt-in for that gate.
+  if (process.env.THUMBGATE_STRICT_KNOWLEDGE_CONFLICT === '1' && result.gate === 'knowledge-conflict-gate') return result;
+  // Warn-by-default: the gate still fired and is recorded; the action is allowed through
+  // with the warning surfaced instead of hard-blocked, so legitimate work is never blocked.
+  return {
+    ...result,
+    decision: 'warn',
+    warnByDefault: true,
+    message: `${result.message}\n\n⚠️ ThumbGate is in warn-by-default mode — this was flagged and logged, not blocked. Set THUMBGATE_STRICT_ENFORCEMENT=1 to hard-block, or THUMBGATE_HOTFIX_BYPASS=1 to disable checks entirely.`,
+  };
+}
+const BREAK_GLASS_CONDITION = 'thumbgate_break_glass';
+const BREAK_GLASS_SETTINGS_GLOBS = [
+  '.claude/settings.local.json',
+  '.claude/settings.json',
+  '**/.claude/settings.local.json',
+  '**/.claude/settings.json',
+  '.codex/config.toml',
+  '**/.codex/config.toml',
+];
+
+function isRuntimePlanGateEnabled() {
+  return process.env.THUMBGATE_PLAN_GATE === '1' || process.env.THUMBGATE_PLAN_GATE === 'true';
+}
 const PR_THREAD_RESOLUTION_CLAIM_PATTERN = '(?:thread|review|comment).*?(?:resolved|verified|checked|addressed|fixed)|(?:resolved|verified|checked|addressed|fixed).*?(?:thread|review|comment)';
 const PR_THREAD_RESOLUTION_REQUIRED_ACTIONS = ['pr_threads_checked', 'thread_resolution_verified'];
 
+function commandScanText(command) {
+  return String(command || '').slice(0, MAX_COMMAND_SCAN_CHARS);
+}
+
+function commandWords(command) {
+  return commandScanText(command).toLowerCase().split(/\s+/).filter(Boolean);
+}
+
+function commandContainsSequence(words, sequence) {
+  if (!Array.isArray(words) || !Array.isArray(sequence) || sequence.length === 0) return false;
+  for (let i = 0; i <= words.length - sequence.length; i += 1) {
+    let matched = true;
+    for (let j = 0; j < sequence.length; j += 1) {
+      if (words[i + j] !== sequence[j]) {
+        matched = false;
+        break;
+      }
+    }
+    if (matched) return true;
+  }
+  return false;
+}
+
+function commandHasPostMethod(words) {
+  for (let i = 0; i < words.length; i += 1) {
+    const word = words[i];
+    if ((word === '-x' || word === '--method') && words[i + 1] === 'post') return true;
+    if (word === '--method=post' || word === '-xpost') return true;
+  }
+  return false;
+}
+
+function isGhApiPrCreateCommand(command) {
+  const words = commandWords(command);
+  if (!commandContainsSequence(words, ['gh', 'api'])) return false;
+  const hasPullsEndpoint = words.some((word) => word === '/pulls' || word.endsWith('/pulls'));
+  if (!hasPullsEndpoint) return false;
+  const fieldFlags = new Set(['-f', '--field', '--raw-field']);
+  const hasFieldWrite = words.some((word) => (
+    fieldFlags.has(word) ||
+    word.startsWith('-f=') ||
+    word.startsWith('--field=') ||
+    word.startsWith('--raw-field=')
+  ));
+  return hasFieldWrite || commandHasPostMethod(words);
+}
+
+function isRecursiveChmodCommand(command) {
+  const words = commandWords(command);
+  const chmodIndex = words.indexOf('chmod');
+  if (chmodIndex === -1) return false;
+  return words.slice(chmodIndex + 1).includes('-r') || words.slice(chmodIndex + 1).some((word) => word.includes('r') && word.startsWith('-'));
+}
+
 // ---------------------------------------------------------------------------
 // Config loading
 // ---------------------------------------------------------------------------
@@ -187,6 +332,27 @@ function sanitizeGlobList(globs) {
   return [...new Set(globs.map((glob) => normalizeGlob(glob)).filter(Boolean))];
 }
 
+// Affected files are compared as repo-relative paths (git --name-only output and
+// inline paths are relative to the repo root). A caller who passes an ABSOLUTE
+// allowedPath (e.g. "/Users/me/proj/src/**") therefore declares a glob that can never
+// match — a silent no-op scope. When repoPath is known, rebase absolute globs that
+// live under it to the repo-relative form so the scope actually applies. Globs already
+// relative, or absolute but outside repoPath, are returned unchanged.
+function rebaseGlobsToRepoRoot(globs, repoPath) {
+  // normalizeGlob strips both leading AND trailing slashes, so a repoPath with a
+  // trailing slash ("/Users/me/proj/") still matches the repo-relative globs.
+  const repoRel = normalizeGlob(repoPath);
+  if (!repoRel) return globs;
+  return globs.map((glob) => {
+    if (glob === repoRel) return '**';
+    if (glob.startsWith(`${repoRel}/`)) {
+      const rebased = glob.slice(repoRel.length + 1);
+      return rebased || '**';
+    }
+    return glob;
+  });
+}
+
 function globToRegExp(glob) {
   const normalized = normalizeGlob(glob);
   let pattern = '^';
@@ -240,6 +406,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,
   };
   const now = Date.now();
   const activeApprovals = state.protectedApprovals.filter((entry) => {
@@ -259,6 +428,7 @@ function saveGovernanceState(state) {
     taskScope: state && state.taskScope ? state.taskScope : null,
     protectedApprovals: Array.isArray(state && state.protectedApprovals) ? state.protectedApprovals : [],
     branchGovernance: state && state.branchGovernance ? state.branchGovernance : null,
+    workflowContract: state && state.workflowContract ? state.workflowContract : null,
   };
   saveJSON(module.exports.GOVERNANCE_STATE_PATH, next);
 }
@@ -270,33 +440,39 @@ function setTaskScope(scopeInput = {}) {
       taskScope: null,
       protectedApprovals: currentState.protectedApprovals,
       branchGovernance: currentState.branchGovernance,
+      workflowContract: null,
     };
     saveGovernanceState(cleared);
+    refreshLocalOnlyConstraint(cleared);
     return null;
   }
 
-  const allowedPaths = sanitizeGlobList(scopeInput.allowedPaths);
+  const repoPath = String(scopeInput.repoPath || '').trim() || null;
+  const allowedPaths = rebaseGlobsToRepoRoot(sanitizeGlobList(scopeInput.allowedPaths), repoPath);
   if (allowedPaths.length === 0) {
     throw new Error('allowedPaths must be a non-empty array');
   }
 
-  const protectedPaths = sanitizeGlobList(
+  const protectedPaths = rebaseGlobsToRepoRoot(sanitizeGlobList(
     Array.isArray(scopeInput.protectedPaths) && scopeInput.protectedPaths.length > 0
       ? scopeInput.protectedPaths
       : DEFAULT_PROTECTED_FILE_GLOBS
-  );
+  ), repoPath);
   const taskScope = {
     taskId: String(scopeInput.taskId || '').trim() || null,
     summary: String(scopeInput.summary || '').trim() || null,
     allowedPaths,
     protectedPaths,
     localOnly: scopeInput.localOnly === true,
-    repoPath: String(scopeInput.repoPath || '').trim() || null,
+    repoPath,
     createdAt: new Date().toISOString(),
     timestamp: Date.now(),
   };
   const state = loadGovernanceState();
   state.taskScope = taskScope;
+  state.workflowContract = scopeInput.workflowContract && typeof scopeInput.workflowContract === 'object'
+    ? scopeInput.workflowContract
+    : null;
   saveGovernanceState(state);
   if (taskScope.localOnly) {
     setConstraint('local_only', true);
@@ -332,11 +508,44 @@ function approveProtectedAction(input = {}) {
   return entry;
 }
 
+function breakGlassEmergency(input = {}) {
+  const reason = String(input.reason || '').trim();
+  if (!reason) {
+    throw new Error('reason is required');
+  }
+
+  const ttlMs = Math.min(clampTtlMs(input.ttlMs, TTL_MS), TTL_MS);
+  const evidence = `BREAK GLASS: ${reason}`;
+  const gates = ['pr_create_allowed', 'pr_threads_checked', BREAK_GLASS_CONDITION];
+  const satisfied = {};
+  for (const gateId of gates) {
+    satisfied[gateId] = satisfyCondition(gateId, evidence);
+  }
+
+  const approval = approveProtectedAction({
+    pathGlobs: BREAK_GLASS_SETTINGS_GLOBS,
+    reason: evidence,
+    evidence,
+    ttlMs,
+  });
+
+  return {
+    ok: true,
+    reason,
+    ttlMs,
+    expiresAt: new Date(Date.now() + ttlMs).toISOString(),
+    satisfied,
+    approval,
+    settingsGlobs: BREAK_GLASS_SETTINGS_GLOBS.slice(),
+  };
+}
+
 function setBranchGovernance(input = {}) {
   if (input && input.clear === true) {
     const state = loadGovernanceState();
     state.branchGovernance = null;
     saveGovernanceState(state);
+    refreshLocalOnlyConstraint(state);
     return null;
   }
 
@@ -387,6 +596,24 @@ function setConstraint(key, value) {
   return constraints[key];
 }
 
+function clearConstraint(key) {
+  const constraints = loadConstraints();
+  delete constraints[key];
+  saveConstraints(constraints);
+}
+
+function refreshLocalOnlyConstraint(governanceState = loadGovernanceState()) {
+  const localOnlyActive = Boolean(
+    (governanceState.taskScope && governanceState.taskScope.localOnly) ||
+    (governanceState.branchGovernance && governanceState.branchGovernance.localOnly)
+  );
+  if (localOnlyActive) {
+    setConstraint('local_only', true);
+  } else {
+    clearConstraint('local_only');
+  }
+}
+
 function isConditionSatisfied(conditionId) {
   const state = loadState();
   const entry = state[conditionId];
@@ -426,7 +653,29 @@ function loadStats() {
 
 function saveStats(stats) { saveJSON(module.exports.STATS_PATH, stats); }
 
-function recordStat(gateId, action, gate) {
+function buildGateActionFingerprint(gateId, options = {}) {
+  if (options.actionFingerprint) return String(options.actionFingerprint);
+  const toolName = options.toolName || options.tool_name || '';
+  const toolInput = options.toolInput || options.tool_input || {};
+  const parts = [toolName];
+  if (typeof toolInput === 'string') {
+    parts.push(toolInput);
+  } else if (toolInput && typeof toolInput === 'object') {
+    parts.push(
+      toolInput.command || '',
+      toolInput.cmd || '',
+      toolInput.file_path || '',
+      toolInput.path || '',
+      toolInput.description || '',
+      toolInput.prompt || '',
+      toolInput.pattern || '',
+    );
+    if (Array.isArray(toolInput.affectedFiles)) parts.push(...toolInput.affectedFiles);
+  }
+  return actionFingerprint(parts);
+}
+
+function recordStat(gateId, action, gate, options = {}) {
   const stats = loadStats();
   if (action === 'block') stats.blocked = (stats.blocked || 0) + 1;
   else if (action === 'warn') stats.warned = (stats.warned || 0) + 1;
@@ -439,6 +688,29 @@ function recordStat(gateId, action, gate) {
   else if (action === 'warn') stats.byGate[gateId].warned += 1;
   else if (action === 'approve') stats.byGate[gateId].pendingApproval = (stats.byGate[gateId].pendingApproval || 0) + 1;
   else if (action === 'log') stats.byGate[gateId].logged = (stats.byGate[gateId].logged || 0) + 1;
+
+  // Track same-action recurrence within a session for first-time fix rate.
+  // Gate-only recurrence over-counts noisy gates; repeats require a stable,
+  // sanitized action fingerprint.
+  if (action === 'block' || action === 'warn') {
+    if (!stats.sessionFiredGates) stats.sessionFiredGates = {};
+    if (!stats.sessionFiredActions) stats.sessionFiredActions = {};
+    const sessionKey = `session_${Math.floor(Date.now() / SESSION_ACTION_TTL_MS)}`;
+    if (!stats.sessionFiredGates[sessionKey]) stats.sessionFiredGates[sessionKey] = {};
+    stats.sessionFiredGates[sessionKey][gateId] = true;
+
+    const fingerprint = buildGateActionFingerprint(gateId, options);
+    if (fingerprint) {
+      if (!stats.sessionFiredActions[sessionKey]) stats.sessionFiredActions[sessionKey] = {};
+      if (!stats.sessionFiredActions[sessionKey][gateId]) stats.sessionFiredActions[sessionKey][gateId] = {};
+      if (stats.sessionFiredActions[sessionKey][gateId][fingerprint]) {
+        stats.recurringBlocks = (stats.recurringBlocks || 0) + 1;
+      } else {
+        stats.sessionFiredActions[sessionKey][gateId][fingerprint] = true;
+      }
+    }
+  }
+
   saveStats(stats);
   // Track lesson freshness when an auto-promoted gate fires
   if (gate && gate.sourceLessonId) {
@@ -452,6 +724,69 @@ function recordStat(gateId, action, gate) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Free-tier daily block cap
+// ---------------------------------------------------------------------------
+
+/**
+ * Count today's gate blocks from stats. Free tier gets FREE_TIER_DAILY_BLOCKS
+ * blocks/day. After the limit, deny → warn + upgrade CTA so the action proceeds
+ * but the user sees they lost protection.
+ */
+function getTodayBlockCount() {
+  const stats = loadStats();
+  const today = todayKey();
+  if (!stats.dailyBlocks || !stats.dailyBlocks[today]) return 0;
+  return stats.dailyBlocks[today];
+}
+
+function incrementTodayBlockCount() {
+  const stats = loadStats();
+  const today = todayKey();
+  if (!stats.dailyBlocks) stats.dailyBlocks = {};
+  // Clean old dates (keep only last 7 days to prevent unbounded growth)
+  const keys = Object.keys(stats.dailyBlocks);
+  if (keys.length > 7) {
+    keys.sort();
+    for (const k of keys.slice(0, keys.length - 7)) {
+      delete stats.dailyBlocks[k];
+    }
+  }
+  stats.dailyBlocks[today] = (stats.dailyBlocks[today] || 0) + 1;
+  saveStats(stats);
+  return stats.dailyBlocks[today];
+}
+
+/**
+ * If the user is free-tier and has exceeded daily block limit, downgrade
+ * a deny result to a warn with an upgrade CTA. Returns null if no cap applies.
+ */
+function applyDailyBlockCap(denyResult) {
+  // Pro, trial, CI, and THUMBGATE_NO_RATE_LIMIT users are uncapped
+  if (isProTier()) return null;
+  if (process.env.CI || process.env.GITHUB_ACTIONS) return null;
+
+  const todayCount = getTodayBlockCount();
+  if (todayCount < FREE_TIER_DAILY_BLOCKS) {
+    // Under limit: allow the block, increment counter
+    incrementTodayBlockCount();
+    return null;
+  }
+
+  // Over limit: downgrade deny → warn with upgrade CTA
+  const remaining = 0;
+  return {
+    decision: 'warn',
+    gate: denyResult.gate,
+    message: `⚠️ ${denyResult.message}\n\n🔓 Daily protection limit reached (${FREE_TIER_DAILY_BLOCKS}/${FREE_TIER_DAILY_BLOCKS} blocks used). This action was allowed through. Upgrade for unlimited protection: https://thumbgate.ai/go/pro`,
+    severity: denyResult.severity,
+    reasoning: (denyResult.reasoning || []).concat([
+      `Free-tier daily block limit (${FREE_TIER_DAILY_BLOCKS}) exceeded — deny downgraded to warn`,
+    ]),
+    dailyBlockCapApplied: true,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Reasoning chain builder
 // ---------------------------------------------------------------------------
@@ -507,9 +842,26 @@ function toRepoRelativePath(filePath, repoRoot) {
   const value = String(filePath || '').trim();
   if (!value) return '';
   if (repoRoot && path.isAbsolute(value)) {
-    const relative = path.relative(repoRoot, value);
-    if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
-      return normalizePosix(relative);
+    const candidates = [[path.resolve(repoRoot), path.resolve(value)]];
+    try {
+      const rootReal = fs.realpathSync.native(repoRoot);
+      let valueReal = null;
+      try {
+        valueReal = fs.realpathSync.native(value);
+      } catch {
+        const parentReal = fs.realpathSync.native(path.dirname(value));
+        valueReal = path.join(parentReal, path.basename(value));
+      }
+      candidates.push([rootReal, valueReal]);
+    } catch {
+      // Fall back to lexical path comparison below.
+    }
+
+    for (const [rootCandidate, valueCandidate] of candidates) {
+      const relative = path.relative(rootCandidate, valueCandidate);
+      if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
+        return normalizePosix(relative);
+      }
     }
   }
   return normalizePosix(value);
@@ -588,7 +940,7 @@ function extractAffectedFiles(toolName, toolInput = {}) {
       }
     }
 
-    if (/\bgit\s+push\b/i.test(command) || /\bgh\s+pr\s+(?:create|merge)\b/i.test(command)) {
+    if (/\bgit\s+push\b/i.test(command) || /\bgh\s+pr\s+(?:create|merge)\b/i.test(command) || isGhApiPrCreateCommand(command)) {
       for (const filePath of getBranchDiffFiles(repoRoot)) {
         files.add(normalizePosix(filePath));
       }
@@ -607,6 +959,7 @@ function isHighRiskAction(toolName, toolInput = {}, affectedFiles = []) {
   const command = String(toolInput.command || '');
   // Original high-risk pattern (git writes, publishes, destructive ops)
   if (HIGH_RISK_BASH_PATTERN.test(command)) return true;
+  if (isGhApiPrCreateCommand(command)) return true;
   // Broadened: any Bash command that modifies files or has side effects.
   // Excludes pure read/analysis commands (node --test, cat, ls, echo, etc.)
   // to avoid false positives on benign operations.
@@ -810,9 +1163,47 @@ function isThreadResolutionEvidenceAction(toolName, toolInput = {}) {
   return /\b(?:gate-satisfy|satisfy_gate|track_action|gh\s+pr\s+(?:view|checks|status)|gh\s+api\b.*(?:reviewThreads|reviews|comments|threads)|git\s+(?:status|diff|show))\b/i.test(command);
 }
 
+// Read-only observability/metrics MCP tools must NEVER be blocked by the pending
+// PR-thread-resolution gate. Reading revenue, the dashboard, gate stats, or a
+// semantic entity cannot advance a "done" claim or mutate any state, so gating it
+// only blinds the operator to their own numbers. This is the exact failure the CEO
+// hit on 2026-06-30: `get_business_metrics` denied with "a git commit was made on a
+// PR branch" — a governance gate eating the observability path. The exempt set is
+// sourced from the canonical `readonly` MCP profile (config/mcp-allowlists.json) so
+// it cannot drift from the product's own definition of "safe to read"; the hard-coded
+// fallback guarantees the core observability tools stay readable even if that policy
+// file is unreadable at runtime.
+const READ_ONLY_TOOL_FALLBACK = new Set([
+  'get_business_metrics', 'describe_semantic_entity', 'describe_reliability_entity',
+  'get_reliability_rules', 'dashboard', 'org_dashboard', 'gate_stats', 'feedback_stats',
+  'feedback_summary', 'session_report', 'generate_operator_artifact', 'settings_status',
+  'get_scope_state', 'get_branch_governance', 'context_provenance', 'native_messaging_audit',
+  'list_harnesses', 'list_intents', 'list_imported_documents', 'get_imported_document',
+  'check_operational_integrity', 'workflow_sentinel', 'recall', 'search_lessons',
+  'retrieve_lessons', 'search_thumbgate', 'unified_context', 'verify_claim',
+]);
+let readOnlyToolCache = null;
+function getReadOnlyToolNames() {
+  if (readOnlyToolCache) return readOnlyToolCache;
+  const names = new Set(READ_ONLY_TOOL_FALLBACK);
+  try {
+    const { getAllowedTools } = require('./mcp-policy');
+    for (const tool of getAllowedTools('readonly')) names.add(tool);
+  } catch (_) {
+    // Policy file missing/malformed — the fallback set still covers the core
+    // observability tools, so the operator can always read state.
+  }
+  readOnlyToolCache = names;
+  return names;
+}
+function isReadOnlyObservabilityTool(toolName) {
+  return Boolean(toolName) && getReadOnlyToolNames().has(toolName);
+}
+
 function evaluatePendingPrThreadResolutionGate(toolName, toolInput = {}) {
   if (!hasAction(PR_THREAD_RESOLUTION_ACTION)) return null;
   if (isThreadResolutionSatisfied()) return null;
+  if (isReadOnlyObservabilityTool(toolName)) return null;
   if (isThreadResolutionEvidenceAction(toolName, toolInput)) return null;
 
   const message = 'A git commit was made on a PR branch. Verify review threads are resolved before the next tool call.';
@@ -844,7 +1235,8 @@ function getLocalOnlyScopeSources(governanceState = {}, constraints = {}) {
 
 function isRemoteSideEffectCommand(toolName, toolInput = {}) {
   if (toolName !== 'Bash') return false;
-  return REMOTE_SIDE_EFFECT_BASH_PATTERN.test(String(toolInput.command || ''));
+  const command = String(toolInput.command || '');
+  return REMOTE_SIDE_EFFECT_BASH_PATTERN.test(command) || isGhApiPrCreateCommand(command);
 }
 
 function evaluateLocalOnlyRemoteSideEffectGate(toolName, toolInput = {}, governanceState = {}, constraints = {}) {
@@ -866,8 +1258,127 @@ function evaluateLocalOnlyRemoteSideEffectGate(toolName, toolInput = {}, governa
   };
 }
 
+function helperRiskReasons(text) {
+  const value = String(text || '');
+  const reasons = [];
+  if (DOWNLOAD_EXEC_CHAIN_PATTERN.test(value)) reasons.push('download-then-execute chain');
+  if (NETWORK_OR_PROCESS_BOUNDARY_PATTERN.test(value)) reasons.push('network/process boundary');
+  if (DESTRUCTIVE_OR_PRIVILEGE_BOUNDARY_PATTERN.test(value)) reasons.push('destructive/privileged side effect');
+  if (/\b(?:child_process|spawn\(|exec\(|execFile\(|subprocess|ProcessBuilder)\b/i.test(value)) {
+    reasons.push('process spawn');
+  }
+  return [...new Set(reasons)];
+}
+
+function readPackageScript(repoRoot, scriptName) {
+  if (!repoRoot || !scriptName) return '';
+  try {
+    const packagePath = path.join(repoRoot, 'package.json');
+    if (!fs.existsSync(packagePath)) return '';
+    const { scripts = {} } = JSON.parse(fs.readFileSync(packagePath, 'utf8')) || {};
+    return typeof scripts[scriptName] === 'string' ? scripts[scriptName] : '';
+  } catch {
+    return '';
+  }
+}
+
+function recordHelperScriptWrite(toolName, toolInput = {}) {
+  if (process.env.THUMBGATE_HELPER_BYPASS_GUARD === '0') return null;
+
+  const affected = extractAffectedFiles(toolName, toolInput);
+  const affectedFiles = affected.files || [];
+  const command = String(toolInput.command || '');
+  const actionContext = extractActionContext(toolName, toolInput);
+  const helperFiles = affectedFiles.filter((filePath) => HELPER_SCRIPT_FILE_PATTERN.test(normalizePosix(filePath)));
+  const packageScriptTouched = affectedFiles.some((filePath) => normalizePosix(filePath) === 'package.json') || /\bpackage\.json\b|\bscripts\./i.test(actionContext);
+  const commandWrite = toolName === 'Bash' && HELPER_WRITE_PATTERN.test(command);
+
+  if (helperFiles.length === 0 && !packageScriptTouched && !commandWrite) return null;
+
+  const riskText = [
+    actionContext,
+    command,
+    helperFiles.join(' '),
+    packageScriptTouched ? 'package.json scripts' : '',
+  ].filter(Boolean).join('\n');
+  const reasons = helperRiskReasons(riskText);
+
+  const metadata = {
+    repoRoot: affected.repoRoot || resolveRepoRoot(toolInput) || null,
+    helperFiles,
+    packageScriptTouched,
+    reasons,
+  };
+  trackAction(HELPER_BYPASS_ACTION, metadata);
+  return metadata;
+}
+
+function evaluateStatefulHelperBypassGate(toolName, toolInput = {}) {
+  if (process.env.THUMBGATE_HELPER_BYPASS_GUARD === '0') return null;
+  if (toolName !== 'Bash') {
+    recordHelperScriptWrite(toolName, toolInput);
+    return null;
+  }
+
+  const command = String(toolInput.command || '').trim();
+  if (!command) return null;
+
+  if (DOWNLOAD_EXEC_CHAIN_PATTERN.test(command)) {
+    return {
+      decision: 'deny',
+      gate: 'stateful-helper-script-bypass',
+      message: 'Download-then-execute chains are blocked before the real action moves below the visible tool call.',
+      severity: 'critical',
+      reasoning: [
+        `Command matched download/execute chain: ${command.slice(0, 180)}`,
+        'PreToolUse must review the whole action chain, not only the first low-risk command',
+      ],
+    };
+  }
+
+  const writeMetadata = recordHelperScriptWrite(toolName, toolInput);
+  const actions = listSessionActions();
+  const recentWrite = actions[HELPER_BYPASS_ACTION];
+  const recentMetadata = recentWrite && recentWrite.metadata && typeof recentWrite.metadata === 'object'
+    ? recentWrite.metadata
+    : null;
+
+  const scriptMatch = command.match(PACKAGE_RUN_PATTERN);
+  const scriptName = scriptMatch ? scriptMatch[1] : '';
+  const repoRoot = resolveRepoRoot(toolInput);
+  const packageScript = scriptName ? readPackageScript(repoRoot, scriptName) : '';
+  const commandBoundaryReasons = helperRiskReasons(`${command}\n${packageScript}`);
+  const executesRecentHelper = HELPER_EXEC_PATTERN.test(command);
+  const runsRecentPackageScript = Boolean(scriptName && recentMetadata && recentMetadata.packageScriptTouched);
+  const recentReasons = recentMetadata && Array.isArray(recentMetadata.reasons) ? recentMetadata.reasons : [];
+  const writeRiskReasons = writeMetadata && Array.isArray(writeMetadata.reasons) ? writeMetadata.reasons : [];
+  const correlatedReasons = [...new Set([...recentReasons, ...writeRiskReasons, ...commandBoundaryReasons])];
+
+  if (
+    (executesRecentHelper || runsRecentPackageScript) &&
+    (recentMetadata || writeMetadata) &&
+    correlatedReasons.length > 0
+  ) {
+    const target = scriptName ? `package script "${scriptName}"` : 'recent helper script';
+    return {
+      decision: 'deny',
+      gate: 'stateful-helper-script-bypass',
+      message: `A recently modified ${target} now crosses a risky boundary. Review it or constrain cwd, network, process, and writable paths before execution.`,
+      severity: 'critical',
+      reasoning: [
+        `Recent helper/package modification: ${(recentMetadata && recentMetadata.helperFiles || []).join(', ') || (recentMetadata && recentMetadata.packageScriptTouched ? 'package.json scripts' : 'current command write')}`,
+        `Execution command: ${command.slice(0, 180)}`,
+        `Risk reasons: ${correlatedReasons.join(', ')}`,
+        'This blocks the helper-script/package-script bypass class raised in external review',
+      ],
+    };
+  }
+
+  return null;
+}
+
 function recordStructuralGateBlock(toolName, toolInput, result) {
-  recordStat(result.gate, 'block');
+  recordStat(result.gate, 'block', null, { toolName, toolInput });
   const auditRecord = recordAuditEvent({
     toolName,
     toolInput,
@@ -898,6 +1409,25 @@ function shouldEnforceTaskScope(gate, governanceState, toolName, toolInput = {},
   return isScopeEnforcedAction(toolName, toolInput, affectedFiles);
 }
 
+function isAgentHookSettingsFile(filePath) {
+  return matchesAnyGlob(filePath, BREAK_GLASS_SETTINGS_GLOBS);
+}
+
+function isBreakGlassSettingsBypass(gate, affectedFiles) {
+  if (!gate || !['task-scope-edit-boundary', 'protected-file-approval-required'].includes(gate.id)) {
+    return false;
+  }
+  if (!isConditionSatisfied(BREAK_GLASS_CONDITION)) return false;
+  return Array.isArray(affectedFiles) && affectedFiles.length > 0 && affectedFiles.every(isAgentHookSettingsFile);
+}
+
+function isBreakGlassSettingsRecoveryAction(toolName, toolInput = {}) {
+  if (!EDIT_LIKE_TOOLS.has(toolName)) return false;
+  if (!isConditionSatisfied(BREAK_GLASS_CONDITION)) return false;
+  const affectedFiles = extractAffectedFiles(toolName, toolInput).files;
+  return affectedFiles.length > 0 && affectedFiles.every(isAgentHookSettingsFile);
+}
+
 function formatFileList(files, limit = 5) {
   const items = Array.isArray(files) ? files.filter(Boolean) : [];
   if (items.length === 0) return 'none';
@@ -1106,8 +1636,19 @@ function checkWhenClause(when, constraints) {
   if (!when || !when.constraints) return true;
   
   for (const [key, expectedValue] of Object.entries(when.constraints)) {
-    const constraint = constraints[key];
-    if (!constraint || constraint.value !== expectedValue) {
+    let value;
+    if (key === 'careful_mode') {
+      const isEnvTrue = process.env.THUMBGATE_CAREFUL_MODE === '1' || 
+                       String(process.env.THUMBGATE_CAREFUL_MODE).toLowerCase() === 'true';
+      value = isEnvTrue || (constraints[key] && constraints[key].value === expectedValue);
+    } else if (key === 'freeze_mode') {
+      value = Boolean(process.env.THUMBGATE_FREEZE_PATHS) || 
+              (constraints[key] && constraints[key].value !== false && constraints[key].value !== null && constraints[key].value !== undefined);
+    } else {
+      const constraint = constraints[key];
+      value = constraint && constraint.value === expectedValue;
+    }
+    if (!value) {
       return false;
     }
   }
@@ -1115,11 +1656,69 @@ function checkWhenClause(when, constraints) {
 }
 
 function matchGate(gate, toolName, toolInput = {}) {
-  const matchText = toolInput.command || toolInput.file_path || toolInput.path || '';
+  let matchText = toolInput.command || toolInput.file_path || toolInput.path || '';
+
+  // Claw/hybrid support: enrich matchText with claw metadata (for EnterpriseClaw/OpenShell/Perplexity hybrid agents)
+  const clawCtx = toolInput.clawContext || toolInput._claw || (toolInput.agentId ? {
+    actionType: toolInput.actionType || 'unknown',
+    agentId: toolInput.agentId || 'unknown',
+    hybridRoute: toolInput.hybridRoute || 'unknown',
+    screenInteraction: !!toolInput.screenInteraction,
+    fileAccess: !!toolInput.fileAccess,
+  } : null);
+
+  if (clawCtx) {
+    const actionType = clawCtx.actionType || clawCtx.claw_action_type || 'unknown';
+    const parts = [
+      matchText,
+      `claw_style: true`,
+      `agent_identity: ${clawCtx.agentId || 'unknown'}`,
+      `claw_action_type: ${actionType}`,
+      `hybrid_route: ${clawCtx.hybridRoute || 'unknown'}`,
+    ];
+
+    if (clawCtx.screenInteraction || actionType.includes('screen')) {
+      parts.push('screen_interaction');
+      parts.push('interact screen');
+    }
+    if (clawCtx.fileAccess || actionType.includes('file') || actionType.includes('fs')) {
+      parts.push('file_system_access');
+      parts.push('local device file system access');
+    }
+    if (actionType === 'dynamic-tool-creation' || actionType.includes('create-tool') || actionType.includes('define-tool')) {
+      parts.push('create tool');
+    }
+
+    matchText = parts.filter(Boolean).join(' | ');
+  }
+
   const affected = extractAffectedFiles(toolName, toolInput);
   const affectedFiles = affected.files;
   const repoRoot = affected.repoRoot;
   const governanceState = loadGovernanceState();
+  const constraints = loadConstraints();
+
+  if (gate.id === 'on-demand-freeze-mode' || (gate.when && gate.when.constraints && gate.when.constraints.freeze_mode)) {
+    let freezePaths = [];
+    if (process.env.THUMBGATE_FREEZE_PATHS) {
+      freezePaths = process.env.THUMBGATE_FREEZE_PATHS.split(',').map(p => p.trim()).filter(Boolean);
+    } else if (constraints.freeze_mode && typeof constraints.freeze_mode.value === 'string') {
+      freezePaths = constraints.freeze_mode.value.split(',').map(p => p.trim()).filter(Boolean);
+    } else if (constraints.freeze_mode && Array.isArray(constraints.freeze_mode.value)) {
+      freezePaths = constraints.freeze_mode.value;
+    } else if (governanceState.taskScope && Array.isArray(governanceState.taskScope.allowedPaths)) {
+      freezePaths = governanceState.taskScope.allowedPaths;
+    }
+
+    if (freezePaths.length > 0) {
+      const outsideFiles = affectedFiles.filter((filePath) => !matchesAnyGlob(filePath, freezePaths));
+      if (outsideFiles.length > 0) {
+        return { matched: true, matchText, affectedFiles };
+      } else {
+        return { matched: false, matchText, affectedFiles };
+      }
+    }
+  }
 
   if (Array.isArray(gate.toolNames) && gate.toolNames.length > 0 && !gate.toolNames.includes(toolName)) {
     return { matched: false, matchText, affectedFiles };
@@ -1129,6 +1728,12 @@ function matchGate(gate, toolName, toolInput = {}) {
     try {
       const regex = new RegExp(gate.pattern);
       if (!regex.test(matchText)) return { matched: false, matchText, affectedFiles };
+      if (gate.id === 'permission-change-approval' && isSafeLocalCredentialHardeningCommand(toolName, toolInput)) {
+        return { matched: false, matchText, affectedFiles };
+      }
+      if (isBreakGlassSettingsBypass(gate, affectedFiles)) {
+        return { matched: false, matchText, affectedFiles };
+      }
     } catch {
       return { matched: false, matchText, affectedFiles };
     }
@@ -1146,6 +1751,9 @@ function matchGate(gate, toolName, toolInput = {}) {
 
   let taskScopeViolation = null;
   if (gate.requireTaskScope) {
+    if (isBreakGlassSettingsBypass(gate, affectedFiles)) {
+      return { matched: false, matchText, affectedFiles };
+    }
     if (!shouldEnforceTaskScope(gate, governanceState, toolName, toolInput, affectedFiles)) {
       return { matched: false, matchText, affectedFiles };
     }
@@ -1155,6 +1763,9 @@ function matchGate(gate, toolName, toolInput = {}) {
 
   let protectedApprovalViolation = null;
   if (gate.requireProtectedApproval) {
+    if (isBreakGlassSettingsBypass(gate, affectedFiles)) {
+      return { matched: false, matchText, affectedFiles };
+    }
     const protectedGlobs = sanitizeGlobList(
       Array.isArray(gate.protectedGlobs) && gate.protectedGlobs.length > 0
         ? gate.protectedGlobs
@@ -1194,9 +1805,40 @@ function matchesGate(gate, toolName, toolInput) {
   return matchGate(gate, toolName, toolInput).matched;
 }
 
+function isSafeLocalCredentialHardeningCommand(toolName, toolInput = {}) {
+  if (toolName !== 'Bash') return false;
+  const command = String(toolInput.command || '').trim();
+  if (!command || isRecursiveChmodCommand(command)) return false;
+  if (/[;&|`$()<>*?[\]{}]/.test(command)) return false;
+
+  const match = command.match(/(?:^|\s)chmod\s+(?:-[fv]\s+)?0?([46]00)\s+(['"]?)(\S+)\2\s*$/i);
+  if (!match) return false;
+
+  const target = match[3];
+  if (!target || target === '/' || target === '~') return false;
+  if (target.includes('..')) return false;
+
+  const normalized = target.replace(/^['"]|['"]$/g, '').toLowerCase();
+  const looksLikeCredentialPath = /(?:^|\/)(?:\.config|\.ssh|\.gnupg|\.aws|\.gcloud|\.gemini|\.resume_secrets|\.thumbgate|secrets?|credentials?)(?:\/|$)/.test(normalized)
+    || /(?:key|secret|token|credential|gemini|gcloud|google|operator).*\.(?:json|pem|key|env)$/i.test(normalized)
+    || /\.(?:pem|key)$/i.test(normalized);
+
+  return looksLikeCredentialPath;
+}
+
 function evaluateMemoryGuard(toolName, toolInput = {}) {
   const affected = extractAffectedFiles(toolName, toolInput);
   const affectedFiles = affected.files;
+  if (isSafeSecretStorageWrite(toolName, toolInput, process.cwd())) {
+    return null;
+  }
+  // Hardening a credential file's permissions (chmod 600 on a key/secret path) is
+  // a safety action, not a risk. The same exemption already guards the
+  // permission-change-approval gate; without it here, `chmod 600 ~/.resume_secrets/key`
+  // gets hard-denied by recurring-negative-memory matching — the opposite of intent.
+  if (isSafeLocalCredentialHardeningCommand(toolName, toolInput)) {
+    return null;
+  }
   if (!isHighRiskAction(toolName, toolInput, affectedFiles)) {
     return null;
   }
@@ -1210,7 +1852,10 @@ function evaluateMemoryGuard(toolName, toolInput = {}) {
   }
 
   const command = String(toolInput.command || '');
-  if (toolName === 'Bash' && /\bgh\s+pr\s+create\b/i.test(command) && isConditionSatisfied('pr_create_allowed')) {
+  const isPrCreateCommand = toolName === 'Bash' && (
+    /\bgh\s+pr\s+create\b/i.test(command) || isGhApiPrCreateCommand(command)
+  );
+  if (isPrCreateCommand && isConditionSatisfied('pr_create_allowed')) {
     const branchGovernanceViolation = buildBranchGovernanceViolation(
       governanceState,
       toolInput,
@@ -1223,7 +1868,10 @@ function evaluateMemoryGuard(toolName, toolInput = {}) {
     }
   }
 
-  if (toolName === 'Bash' && /\b(?:gh\s+pr\s+(?:create|merge)|gh\s+release\s+create|git\s+tag\b|(?:npm|yarn|pnpm)\s+publish\b)\b/i.test(command)) {
+  if (toolName === 'Bash' && (
+    /\b(?:gh\s+pr\s+(?:create|merge)|gh\s+release\s+create|git\s+tag\b|(?:npm|yarn|pnpm)\s+publish\b)\b/i.test(command) ||
+    isGhApiPrCreateCommand(command)
+  )) {
     const branchGovernanceViolation = buildBranchGovernanceViolation(
       governanceState,
       toolInput,
@@ -1261,7 +1909,14 @@ function evaluateMemoryGuard(toolName, toolInput = {}) {
     filePath: toolInput.file_path || toolInput.path || null,
     affectedFiles,
   });
-  const guard = hybrid.evaluatePretool(toolName, serializedInput);
+  // Claw/hybrid support: pass context if agent provides claw metadata (for EnterpriseClaw/OpenShell/Perplexity hybrid agents)
+  let guard;
+  if (toolInput && (toolInput.clawContext || toolInput._claw || toolInput.hybridRoute || toolInput.agentId)) {
+    const clawCtx = toolInput.clawContext || toolInput._claw || { actionType: toolInput.actionType || 'unknown', agentId: toolInput.agentId || 'unknown', hybridRoute: toolInput.hybridRoute || 'unknown' };
+    guard = hybrid.evaluateClawPretool ? hybrid.evaluateClawPretool(toolName, serializedInput, clawCtx) : hybrid.evaluatePretool(toolName, serializedInput);
+  } else {
+    guard = hybrid.evaluatePretool(toolName, serializedInput);
+  }
   if (!guard || guard.mode === 'allow') {
     return null;
   }
@@ -1374,6 +2029,19 @@ async function checkMetricCondition(metricCondition) {
   return true;
 }
 
+/**
+ * Whether this run is autonomous — i.e. no human is present to resolve an
+ * `approve` (human-in-the-loop) gate. Opt-in ONLY via THUMBGATE_AUTONOMOUS=1
+ * (or "true"); interactive and existing CI behavior is unchanged unless an
+ * operator explicitly sets it. In an autonomous agent loop an approval gate has
+ * nobody to sign off, so it must fail CLOSED (deny) rather than defer forever or
+ * slip through — a guardrail has to guard precisely when it is unattended.
+ */
+function isAutonomousRun() {
+  const raw = String(process.env.THUMBGATE_AUTONOMOUS || '').trim().toLowerCase();
+  return raw === '1' || raw === 'true';
+}
+
 async function evaluateGatesAsync(toolName, toolInput, configPath) {
   let config;
   try {
@@ -1399,10 +2067,26 @@ async function evaluateGatesAsync(toolName, toolInput, configPath) {
   if (localOnlyRemoteSideEffectGate) {
     return recordStructuralGateBlock(toolName, toolInput, localOnlyRemoteSideEffectGate);
   }
+  const statefulHelperBypassGate = evaluateStatefulHelperBypassGate(toolName, toolInput);
+  if (statefulHelperBypassGate) {
+    return recordStructuralGateBlock(toolName, toolInput, statefulHelperBypassGate);
+  }
+  if (isBreakGlassSettingsRecoveryAction(toolName, toolInput)) {
+    recordAuditEvent({
+      toolName,
+      toolInput,
+      decision: 'allow',
+      gateId: BREAK_GLASS_CONDITION,
+      message: 'Break-glass recovery allowed hook settings edit',
+      severity: 'high',
+      source: 'gates-engine',
+    });
+    return null;
+  }
 
   const pendingThreadResolutionGate = evaluatePendingPrThreadResolutionGate(toolName, toolInput);
   if (pendingThreadResolutionGate) {
-    recordStat(pendingThreadResolutionGate.gate, 'block');
+    recordStat(pendingThreadResolutionGate.gate, 'block', null, { toolName, toolInput });
     const auditRecord = recordAuditEvent({
       toolName,
       toolInput,
@@ -1418,7 +2102,7 @@ async function evaluateGatesAsync(toolName, toolInput, configPath) {
 
   const boostedRiskGuard = evaluateBoostedRiskTagGuard(toolName, toolInput);
   if (boostedRiskGuard) {
-    recordStat(boostedRiskGuard.gate, 'block');
+    recordStat(boostedRiskGuard.gate, 'block', null, { toolName, toolInput });
     const auditRecord = recordAuditEvent({
       toolName,
       toolInput,
@@ -1432,6 +2116,23 @@ async function evaluateGatesAsync(toolName, toolInput, configPath) {
     return boostedRiskGuard;
   }
 
+  // Tier 1b: Planning and Trajectory (v1.26.0 - CodeRabbit Pattern).
+  // Keep runtime enforcement explicit so advisory planning checks do not mask
+  // higher-priority deny/approve gates in established workflows.
+  if (isRuntimePlanGateEnabled()) {
+    const planGate = evaluatePlanGate(toolName, toolInput);
+    if (planGate) {
+      recordStat(planGate.gate, planGate.decision === 'deny' ? 'block' : 'warn', null, { toolName, toolInput });
+      return planGate;
+    }
+
+    const trajectory = getTrajectoryScore();
+    if (trajectory.isDrifting) {
+      recordStat('strategic-drift', 'block', null, { toolName, toolInput });
+      return { decision: 'deny', gate: 'strategic-drift', message: trajectory.message, severity: 'high' };
+    }
+  }
+
   // Fast-path: feedback/recall tools skip metric gates entirely (avoids Stripe API calls)
   const METRIC_SKIP_TOOLS = ['capture_feedback', 'feedback_stats', 'recall', 'feedback_summary', 'prevention_rules'];
   const skipMetrics = METRIC_SKIP_TOOLS.includes(toolName);
@@ -1477,23 +2178,48 @@ async function evaluateGatesAsync(toolName, toolInput, configPath) {
     });
 
     if (gate.action === 'block') {
-      recordStat(gate.id, 'block', gate);
-      const result = { decision: 'deny', gate: gate.id, message, severity: gate.severity, reasoning };
+      const denyResult = { decision: 'deny', gate: gate.id, message, severity: gate.severity, reasoning };
+      // Free-tier daily block cap: after N blocks/day, deny → warn + upgrade CTA
+      const cappedResult = applyDailyBlockCap(denyResult);
+      if (cappedResult) {
+        recordStat(gate.id, 'warn', gate, { toolName, toolInput });
+        const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'warn', gateId: gate.id, message: cappedResult.message, severity: gate.severity, source: 'gates-engine', dailyBlockCapApplied: true });
+        auditToFeedback(auditRecord);
+        return cappedResult;
+      }
+      recordStat(gate.id, 'block', gate, { toolName, toolInput });
       const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'deny', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
       auditToFeedback(auditRecord);
-      return result;
+      return denyResult;
     }
 
     if (gate.action === 'approve') {
-      recordStat(gate.id, 'approve', gate);
-      const result = { decision: 'approve', gate: gate.id, message, severity: gate.severity, reasoning, requiresApproval: true };
-      const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'approve', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
+      const approvalEnabled = process.env.THUMBGATE_APPROVAL_GATES !== '0';
+      if (approvalEnabled) {
+        if (isAutonomousRun()) {
+          // Autonomous run: no human to approve. Fail CLOSED so the actions that
+          // most need sign-off cannot slip through unattended.
+          const failClosedMessage = `[autonomous run — no approver present, failing closed] ${message}`;
+          recordStat(gate.id, 'block', gate, { toolName, toolInput });
+          const failClosedAudit = recordAuditEvent({ toolName, toolInput, decision: 'deny', gateId: gate.id, message: failClosedMessage, severity: gate.severity, source: 'gates-engine', autonomousFailClosed: true });
+          auditToFeedback(failClosedAudit);
+          return { decision: 'deny', gate: gate.id, message: failClosedMessage, severity: gate.severity, reasoning, requiresApproval: true, failedClosed: true };
+        }
+        recordStat(gate.id, 'approve', gate, { toolName, toolInput });
+        const result = { decision: 'approve', gate: gate.id, message, severity: gate.severity, reasoning, requiresApproval: true };
+        const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'approve', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
+        auditToFeedback(auditRecord);
+        return result;
+      }
+      recordStat(gate.id, 'warn', gate, { toolName, toolInput });
+      const result = { decision: 'warn', gate: gate.id, message: `[approval gate disabled] ${message}`, severity: gate.severity, reasoning };
+      const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'warn', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
       auditToFeedback(auditRecord);
       return result;
     }
 
     if (gate.action === 'log') {
-      recordStat(gate.id, 'log', gate);
+      recordStat(gate.id, 'log', gate, { toolName, toolInput });
       const result = { decision: 'log', gate: gate.id, message, severity: gate.severity, reasoning, logged: true };
       const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'log', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
       auditToFeedback(auditRecord);
@@ -1502,7 +2228,7 @@ async function evaluateGatesAsync(toolName, toolInput, configPath) {
     }
 
     if (gate.action === 'warn') {
-      recordStat(gate.id, 'warn', gate);
+      recordStat(gate.id, 'warn', gate, { toolName, toolInput });
       const result = { decision: 'warn', gate: gate.id, message, severity: gate.severity, reasoning };
       const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'warn', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
       auditToFeedback(auditRecord);
@@ -1510,14 +2236,15 @@ async function evaluateGatesAsync(toolName, toolInput, configPath) {
     }
   }
 
-  const sentinelReport = evaluateWorkflowSentinel(toolName, toolInput, {
+  const skipAdvisoryGuards = isSafeSecretStorageWrite(toolName, toolInput, process.cwd());
+  const sentinelReport = skipAdvisoryGuards ? null : evaluateWorkflowSentinel(toolName, toolInput, {
     governanceState,
   });
   const sentinelDecision = recordSentinelDecision(sentinelReport, toolName, toolInput);
   const memoryGuard = evaluateMemoryGuard(toolName, toolInput);
   if (memoryGuard) {
     const enrichedMemoryGuard = enrichResultWithSentinel(memoryGuard, sentinelReport);
-    recordStat(enrichedMemoryGuard.gate, 'block');
+    recordStat(enrichedMemoryGuard.gate, 'block', null, { toolName, toolInput });
     recordMemoryGuardDecision(sentinelDecision, enrichedMemoryGuard);
     const auditRecord = recordAuditEvent({
       toolName,
@@ -1534,7 +2261,7 @@ async function evaluateGatesAsync(toolName, toolInput, configPath) {
 
   if (sentinelReport && sentinelReport.decision !== 'allow') {
     const sentinelResult = buildSentinelGateResult(sentinelReport);
-    recordStat(sentinelResult.gate, sentinelResult.decision === 'deny' ? 'block' : 'warn');
+    recordStat(sentinelResult.gate, sentinelResult.decision === 'deny' ? 'block' : 'warn', null, { toolName, toolInput });
     recordSentinelBlockDecision(sentinelDecision, sentinelResult);
     const auditRecord = recordAuditEvent({
       toolName,
@@ -1580,10 +2307,26 @@ function evaluateGates(toolName, toolInput, configPath) {
   if (localOnlyRemoteSideEffectGate) {
     return recordStructuralGateBlock(toolName, toolInput, localOnlyRemoteSideEffectGate);
   }
+  const statefulHelperBypassGate = evaluateStatefulHelperBypassGate(toolName, toolInput);
+  if (statefulHelperBypassGate) {
+    return recordStructuralGateBlock(toolName, toolInput, statefulHelperBypassGate);
+  }
+  if (isBreakGlassSettingsRecoveryAction(toolName, toolInput)) {
+    recordAuditEvent({
+      toolName,
+      toolInput,
+      decision: 'allow',
+      gateId: BREAK_GLASS_CONDITION,
+      message: 'Break-glass recovery allowed hook settings edit',
+      severity: 'high',
+      source: 'gates-engine',
+    });
+    return null;
+  }
 
   const pendingThreadResolutionGate = evaluatePendingPrThreadResolutionGate(toolName, toolInput);
   if (pendingThreadResolutionGate) {
-    recordStat(pendingThreadResolutionGate.gate, 'block');
+    recordStat(pendingThreadResolutionGate.gate, 'block', null, { toolName, toolInput });
     const auditRecord = recordAuditEvent({
       toolName,
       toolInput,
@@ -1599,7 +2342,7 @@ function evaluateGates(toolName, toolInput, configPath) {
 
   const boostedRiskGuard = evaluateBoostedRiskTagGuard(toolName, toolInput);
   if (boostedRiskGuard) {
-    recordStat(boostedRiskGuard.gate, 'block');
+    recordStat(boostedRiskGuard.gate, 'block', null, { toolName, toolInput });
     const auditRecord = recordAuditEvent({
       toolName,
       toolInput,
@@ -1613,6 +2356,23 @@ function evaluateGates(toolName, toolInput, configPath) {
     return boostedRiskGuard;
   }
 
+  // Tier 1b: Planning and Trajectory (v1.26.0 - CodeRabbit Pattern).
+  // Keep runtime enforcement explicit so advisory planning checks do not mask
+  // higher-priority deny/approve gates in established workflows.
+  if (isRuntimePlanGateEnabled()) {
+    const planGate = evaluatePlanGate(toolName, toolInput);
+    if (planGate) {
+      recordStat(planGate.gate, planGate.decision === 'deny' ? 'block' : 'warn', null, { toolName, toolInput });
+      return planGate;
+    }
+
+    const trajectory = getTrajectoryScore();
+    if (trajectory.isDrifting) {
+      recordStat('strategic-drift', 'block', null, { toolName, toolInput });
+      return { decision: 'deny', gate: 'strategic-drift', message: trajectory.message, severity: 'high' };
+    }
+  }
+
   for (const gate of config.gates) {
     const matchDetails = matchGate(gate, toolName, toolInput);
     if (!matchDetails.matched) continue;
@@ -1631,23 +2391,48 @@ function evaluateGates(toolName, toolInput, configPath) {
     const reasoning = buildReasoning(gate, toolName, toolInput, matchDetails);
 
     if (gate.action === 'block') {
-      recordStat(gate.id, 'block', gate);
-      const result = { decision: 'deny', gate: gate.id, message, severity: gate.severity, reasoning };
+      const denyResult = { decision: 'deny', gate: gate.id, message, severity: gate.severity, reasoning };
+      // Free-tier daily block cap: after N blocks/day, deny → warn + upgrade CTA
+      const cappedResult = applyDailyBlockCap(denyResult);
+      if (cappedResult) {
+        recordStat(gate.id, 'warn', gate, { toolName, toolInput });
+        const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'warn', gateId: gate.id, message: cappedResult.message, severity: gate.severity, source: 'gates-engine', dailyBlockCapApplied: true });
+        auditToFeedback(auditRecord);
+        return cappedResult;
+      }
+      recordStat(gate.id, 'block', gate, { toolName, toolInput });
       const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'deny', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
       auditToFeedback(auditRecord);
-      return result;
+      return denyResult;
     }
 
     if (gate.action === 'approve') {
-      recordStat(gate.id, 'approve', gate);
-      const result = { decision: 'approve', gate: gate.id, message, severity: gate.severity, reasoning, requiresApproval: true };
-      const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'approve', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
+      const approvalEnabled = process.env.THUMBGATE_APPROVAL_GATES !== '0';
+      if (approvalEnabled) {
+        if (isAutonomousRun()) {
+          // Autonomous run: no human to approve. Fail CLOSED so the actions that
+          // most need sign-off cannot slip through unattended.
+          const failClosedMessage = `[autonomous run — no approver present, failing closed] ${message}`;
+          recordStat(gate.id, 'block', gate, { toolName, toolInput });
+          const failClosedAudit = recordAuditEvent({ toolName, toolInput, decision: 'deny', gateId: gate.id, message: failClosedMessage, severity: gate.severity, source: 'gates-engine', autonomousFailClosed: true });
+          auditToFeedback(failClosedAudit);
+          return { decision: 'deny', gate: gate.id, message: failClosedMessage, severity: gate.severity, reasoning, requiresApproval: true, failedClosed: true };
+        }
+        recordStat(gate.id, 'approve', gate, { toolName, toolInput });
+        const result = { decision: 'approve', gate: gate.id, message, severity: gate.severity, reasoning, requiresApproval: true };
+        const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'approve', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
+        auditToFeedback(auditRecord);
+        return result;
+      }
+      recordStat(gate.id, 'warn', gate, { toolName, toolInput });
+      const result = { decision: 'warn', gate: gate.id, message: `[approval gate disabled] ${message}`, severity: gate.severity, reasoning };
+      const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'warn', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
       auditToFeedback(auditRecord);
       return result;
     }
 
     if (gate.action === 'log') {
-      recordStat(gate.id, 'log', gate);
+      recordStat(gate.id, 'log', gate, { toolName, toolInput });
       const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'log', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
       auditToFeedback(auditRecord);
       // 'log' action allows the tool call to proceed — continue to next gate
@@ -1655,7 +2440,7 @@ function evaluateGates(toolName, toolInput, configPath) {
     }
 
     if (gate.action === 'warn') {
-      recordStat(gate.id, 'warn', gate);
+      recordStat(gate.id, 'warn', gate, { toolName, toolInput });
       const result = { decision: 'warn', gate: gate.id, message, severity: gate.severity, reasoning };
       const auditRecord = recordAuditEvent({ toolName, toolInput, decision: 'warn', gateId: gate.id, message, severity: gate.severity, source: 'gates-engine' });
       auditToFeedback(auditRecord);
@@ -1663,14 +2448,15 @@ function evaluateGates(toolName, toolInput, configPath) {
     }
   }
 
-  const sentinelReport = evaluateWorkflowSentinel(toolName, toolInput, {
+  const skipAdvisoryGuards = isSafeSecretStorageWrite(toolName, toolInput, process.cwd());
+  const sentinelReport = skipAdvisoryGuards ? null : evaluateWorkflowSentinel(toolName, toolInput, {
     governanceState,
   });
   const sentinelDecision = recordSentinelDecision(sentinelReport, toolName, toolInput);
   const memoryGuard = evaluateMemoryGuard(toolName, toolInput);
   if (memoryGuard) {
     const enrichedMemoryGuard = enrichResultWithSentinel(memoryGuard, sentinelReport);
-    recordStat(enrichedMemoryGuard.gate, 'block');
+    recordStat(enrichedMemoryGuard.gate, 'block', null, { toolName, toolInput });
     recordMemoryGuardDecision(sentinelDecision, enrichedMemoryGuard);
     const auditRecord = recordAuditEvent({
       toolName,
@@ -1687,7 +2473,7 @@ function evaluateGates(toolName, toolInput, configPath) {
 
   if (sentinelReport && sentinelReport.decision !== 'allow') {
     const sentinelResult = buildSentinelGateResult(sentinelReport);
-    recordStat(sentinelResult.gate, sentinelResult.decision === 'deny' ? 'block' : 'warn');
+    recordStat(sentinelResult.gate, sentinelResult.decision === 'deny' ? 'block' : 'warn', null, { toolName, toolInput });
     recordSentinelBlockDecision(sentinelDecision, sentinelResult);
     const auditRecord = recordAuditEvent({
       toolName,
@@ -1707,14 +2493,43 @@ function evaluateGates(toolName, toolInput, configPath) {
   return null;
 }
 
-function buildSecretGuardResult(scanResult) {
+// Turn a secret-exfiltration block into actionable guidance that names the
+// safe path, instead of a dead-end that drives agents toward brittle
+// workarounds (e.g. writing secrets to /tmp). The vault dirs referenced here
+// are the SAME constant the scanner whitelists, so the hint can never drift
+// from enforcement.
+function buildSecretRemediation(toolName = '', toolInput = {}) {
+  const vaultDirs = (SAFE_SECRET_STORAGE_DIRS || []).map((dir) => `~/${dir}`);
+  const primaryVault = vaultDirs[0] || '~/.resume_secrets';
+  const vaultList = vaultDirs.join(', ') || primaryVault;
+
+  if (EDIT_LIKE_TOOLS && EDIT_LIKE_TOOLS.has(toolName)) {
+    const target = toolInput.file_path || toolInput.path || toolInput.filePath || toolInput.target_path;
+    const where = target ? ` (you targeted ${redactText(String(target))})` : '';
+    return `To store this secret safely, write it with the Write/Edit tool to a file under ${vaultList}${where}. `
+      + `Those locations are whitelisted for secret storage and will NOT be blocked. `
+      + `Do not route around this by writing to /tmp or another path — that leaves the secret in a world-readable location and does not make it safe.`;
+  }
+
+  if (toolName === 'Bash') {
+    return `Do not inline a live secret literal into a shell command — it leaks into shell history and process args. `
+      + `Instead, store the value with the Write tool to a file under ${vaultList}, then reference it via an environment variable or by reading that file at runtime.`;
+  }
+
+  return `Store secrets in the whitelisted vault (${vaultList}) using the Write tool rather than passing the literal through this action.`;
+}
+
+function buildSecretGuardResult(scanResult, context = {}) {
+  const remediation = buildSecretRemediation(context.toolName, context.toolInput || {});
+  const summary = buildSafeSummary(
+    scanResult.findings,
+    'Blocked because the action appears to expose secret material'
+  );
   return {
     decision: 'deny',
     gate: 'secret-exfiltration',
-    message: buildSafeSummary(
-      scanResult.findings,
-      'Blocked because the action appears to expose secret material'
-    ),
+    message: `${summary}. ${remediation}`,
+    remediation,
     severity: 'critical',
     secretScan: {
       provider: scanResult.provider,
@@ -1793,9 +2608,15 @@ function evaluateSecretGuard(input = {}) {
   if (!scanResult.detected) {
     return null;
   }
-  recordStat('secret-exfiltration', 'block');
+  recordStat('secret-exfiltration', 'block', null, {
+    toolName: input.tool_name || input.toolName || 'unknown',
+    toolInput: input.tool_input || {},
+  });
   recordSecretViolation(input, scanResult);
-  const result = buildSecretGuardResult(scanResult);
+  const result = buildSecretGuardResult(scanResult, {
+    toolName: input.tool_name || input.toolName,
+    toolInput: input.tool_input || {},
+  });
   // Audit trail: record secret guard denial
   const auditRecord = recordAuditEvent({
     toolName: input.tool_name || input.toolName || 'unknown',
@@ -1811,15 +2632,55 @@ function evaluateSecretGuard(input = {}) {
 }
 
 // ---------------------------------------------------------------------------
+function isApprovalGatesEnabled() {
+  return process.env.THUMBGATE_APPROVAL_GATES !== '0';
+}
+
 // PreToolUse hook interface (stdin/stdout JSON)
 // ---------------------------------------------------------------------------
 
-function buildReminderOutput(context) {
+function buildPreToolUseOutput(fields = {}) {
   return {
+    hookEventName: 'PreToolUse',
+    ...fields,
+  };
+}
+
+function buildReminderOutput(context) {
+  return buildPreToolUseOutput({
     additionalContext: context,
     systemReminder: context,
     thumbgateSystemReminder: context,
-  };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Upgrade nudge: surfaces Pro value at usage milestones and trial expiry.
+// Block-action Pro CTA: brief upgrade mention after a deny/warn decision.
+// Highest-intent moment — user just saw ThumbGate save them from a mistake.
+// ---------------------------------------------------------------------------
+
+function buildBlockActionProCta() {
+  try {
+    if (process.env.THUMBGATE_NO_NUDGE === '1') return null;
+    if (process.env.CI || process.env.GITHUB_ACTIONS) return null;
+    if (isProTier()) return null;
+    if (isInTrialPeriod()) return null; // Already have full access
+
+    const stats = loadStats();
+    const totalBlocks = stats.blocked || 0;
+    if (totalBlocks < 5) return null; // Too early — let them experience the product
+
+    if (totalBlocks < 25) {
+      return '\n\n💡 Pro: keep this rule synced across laptops, CI, containers, and agent runtimes → thumbgate.ai/go/pro';
+    }
+    if (totalBlocks < 100) {
+      return `\n\n💡 ${totalBlocks} actions blocked. Pro keeps these lessons/rules synced everywhere → thumbgate.ai/go/pro ($19/mo)`;
+    }
+    return `\n\n💡 ${totalBlocks} mistakes caught. Your team could use shared hosted enforcement → thumbgate.ai/go/pro`;
+  } catch (_) {
+    return null;
+  }
 }
 
 function formatOutput(result, behavioralContext) {
@@ -1838,13 +2699,28 @@ function formatOutput(result, behavioralContext) {
     : '';
 
   if (result.decision === 'deny') {
+    const reminder = behavioralContext ? buildReminderOutput(behavioralContext) : {};
+    const reminderSuffix = behavioralContext ? `\n\nSystem reminder:\n${behavioralContext}` : '';
+    const proCta = buildBlockActionProCta() || '';
+    return JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        ...reminder,
+        permissionDecision: 'deny',
+        permissionDecisionReason: `[GATE:${result.gate}] ${result.message}${reasoningSuffix}${reminderSuffix}${proCta}`,
+      },
+    });
+  }
+
+  if (result.decision === 'approve') {
     const reminder = behavioralContext ? buildReminderOutput(behavioralContext) : {};
     const reminderSuffix = behavioralContext ? `\n\nSystem reminder:\n${behavioralContext}` : '';
     return JSON.stringify({
       hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
         ...reminder,
         permissionDecision: 'deny',
-        permissionDecisionReason: `[GATE:${result.gate}] ${result.message}${reasoningSuffix}${reminderSuffix}`,
+        permissionDecisionReason: `[GATE:${result.gate}] APPROVAL REQUIRED: ${result.message} — Ask the human to confirm this action before proceeding.${reasoningSuffix}${reminderSuffix}`,
       },
     });
   }
@@ -1854,6 +2730,7 @@ function formatOutput(result, behavioralContext) {
     const context = `[GATE:${result.gate}] WARNING: ${result.message}${reasoningSuffix}${extra}`;
     return JSON.stringify({
       hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
         additionalContext: context,
         ...(behavioralContext ? {
           systemReminder: behavioralContext,
@@ -1977,9 +2854,7 @@ function buildRecentCorrectiveActionsContext(options = {}) {
 function buildRelevantLessonContext(toolName, toolInput) {
   if (!toolName) return null;
 
-  const { retrieveRelevantLessons } = loadOptionalModule('./lesson-retrieval', () => ({
-    retrieveRelevantLessons: () => [],
-  }));
+  const { retrieveRelevantLessons, calculateRetrievalEntropy } = loadOptionalModule("./lesson-retrieval", () => ({ retrieveRelevantLessons: () => [], calculateRetrievalEntropy: () => 0 }));
 
   // Extract a searchable action context from the tool input
   const actionContext = extractActionContext(toolName, toolInput);
@@ -1987,32 +2862,113 @@ function buildRelevantLessonContext(toolName, toolInput) {
 
   try {
     const lessons = retrieveRelevantLessons(toolName, actionContext, { maxResults: 3 });
-    // retrieveRelevantLessons already filters at relevanceScore > 0.1 internally;
-    // any negative lesson that survives retrieval is relevant enough to surface.
-    const negative = lessons.filter((l) => l.signal === 'negative');
-    if (negative.length === 0) return null;
-
-    const formatted = negative.map((l) => {
-      const title = (l.title || '').replace(/^MISTAKE:\s*/, '').slice(0, 140);
-      const advice = extractAvoidanceAdvice(l.content);
-      return advice ? `  • ${title}\n    → ${advice}` : `  • ${title}`;
-    });
 
-    return `[ThumbGate] Past mistakes relevant to this action — read before proceeding:\n${formatted.join('\n')}`;
+    const entropy = calculateRetrievalEntropy(lessons);
+    if (entropy > KNOWLEDGE_ENTROPY_THRESHOLD) {
+      return buildKnowledgeConflictContext(toolName, toolInput, lessons, entropy);
+    }
+    return formatNegativeLessonContext(lessons);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Async counterpart of buildRelevantLessonContext: uses HYBRID (dense embeddings +
+ * lexical) retrieval so the agent is warned about semantically-related past mistakes
+ * even when they share no keywords with the current action. Wired into runAsync.
+ * Degrades to the lexical result automatically when no embedder is available.
+ */
+async function buildRelevantLessonContextAsync(toolName, toolInput) {
+  if (!toolName) return null;
+
+  const { retrieveRelevantLessonsAsync, retrieveRelevantLessons, calculateRetrievalEntropy } = loadOptionalModule(
+    './lesson-retrieval',
+    () => ({ retrieveRelevantLessonsAsync: null, retrieveRelevantLessons: () => [], calculateRetrievalEntropy: () => 0 }),
+  );
+
+  const actionContext = extractActionContext(toolName, toolInput);
+  if (!actionContext) return null;
+
+  try {
+    const lessons = retrieveRelevantLessonsAsync
+      ? await retrieveRelevantLessonsAsync(toolName, actionContext, { maxResults: 3 })
+      : retrieveRelevantLessons(toolName, actionContext, { maxResults: 3 });
+    
+    // Knowledge Conflict Detection: if retrieved lessons have high sentiment entropy,
+    // it indicates conflicting past evidence. Warn by default; hard-block only in
+    // strict mode for external/destructive side-effect commands.
+    const entropy = calculateRetrievalEntropy(lessons);
+    if (entropy > KNOWLEDGE_ENTROPY_THRESHOLD) {
+      return buildKnowledgeConflictContext(toolName, toolInput, lessons, entropy);
+    }
+
+    return formatNegativeLessonContext(lessons);
   } catch {
     return null;
   }
 }
 
+/**
+ * Shared formatter: render the negative (mistake) lessons that survived retrieval
+ * into the PreToolUse warning block. Retrieval already filters by relevance, so any
+ * negative lesson present is relevant enough to surface.
+ */
+function formatNegativeLessonContext(lessons) {
+  const negative = (lessons || []).filter((l) => l.signal === 'negative');
+  if (negative.length === 0) return null;
+
+  const formatted = negative.map((l) => {
+    const title = (l.title || '').replace(/^MISTAKE:\s*/, '').slice(0, 140);
+    const advice = extractAvoidanceAdvice(l.content);
+    return advice ? `  • ${title}\n    → ${advice}` : `  • ${title}`;
+  });
+
+  return `[ThumbGate] Past mistakes relevant to this action — read before proceeding:\n${formatted.join('\n')}`;
+}
+
+function isStrictKnowledgeConflictMode() {
+  return process.env.THUMBGATE_STRICT_KNOWLEDGE_CONFLICT === '1'
+    || process.env.THUMBGATE_STRICT_KNOWLEDGE_CONFLICT === 'true';
+}
+
+function isKnowledgeConflictHardBlockAction(toolName, toolInput = {}) {
+  if (!isStrictKnowledgeConflictMode()) return false;
+  if (EDIT_LIKE_TOOLS.has(toolName)) return true;
+  if (toolName !== 'Bash') return false;
+  return KNOWLEDGE_CONFLICT_STRICT_BASH_PATTERN.test(String(toolInput.command || ''));
+}
+
+function buildKnowledgeConflictContext(toolName, toolInput, lessons, entropy) {
+  const lessonContext = formatNegativeLessonContext(lessons);
+  const message = `Knowledge conflict warning: retrieved lessons disagree for this action (entropy ${entropy}). Treat the reminders below as cautionary context, but do not stop unrelated work solely because memory is noisy.`;
+
+  if (isKnowledgeConflictHardBlockAction(toolName, toolInput)) {
+    recordStat('retrieval_entropy_high', 'block', null, { toolName, toolInput });
+    return {
+      decision: 'deny',
+      gate: 'knowledge-conflict-gate',
+      message: `✗ THUMBGATE: ${message} Strict mode is enabled for destructive or external side-effect actions; verify intent or narrow the task before proceeding.`,
+      severity: 'high',
+    };
+  }
+
+  recordStat('retrieval_entropy_high', 'warn', null, { toolName, toolInput });
+  return mergeContextStrings(`[ThumbGate] ${message}`, lessonContext);
+}
+
 function extractActionContext(toolName, toolInput) {
   if (!toolInput) return toolName;
   const parts = [toolName];
   if (toolInput.command) parts.push(String(toolInput.command).slice(0, 400));
   if (toolInput.file_path) parts.push(String(toolInput.file_path));
+  if (toolInput.content) parts.push(String(toolInput.content).slice(0, 600));
+  if (toolInput.new_string) parts.push(String(toolInput.new_string).slice(0, 600));
+  if (toolInput.old_string) parts.push(String(toolInput.old_string).slice(0, 240));
   if (toolInput.description) parts.push(String(toolInput.description).slice(0, 200));
   if (toolInput.prompt) parts.push(String(toolInput.prompt).slice(0, 400));
   if (toolInput.pattern) parts.push(String(toolInput.pattern).slice(0, 200));
-  return parts.filter(Boolean).join(' ');
+  return sanitizeFeedbackText(parts.filter(Boolean).join(' ')) || toolName;
 }
 
 function extractAvoidanceAdvice(content) {
@@ -2041,6 +2997,13 @@ async function runAsync(input) {
 
   const toolName = input.tool_name || '';
   const toolInput = input.tool_input || {};
+  const safeSecretStorageWrite = isSafeSecretStorageWrite(toolName, toolInput, process.cwd());
+
+  const sequenceGuard = evaluateSequenceState(toolName, toolInput);
+  if (sequenceGuard && sequenceGuard.decision === 'deny') {
+    return formatOutput(applyEnforcementPosture(sequenceGuard));
+  }
+
   const result = await evaluateGatesAsync(toolName, toolInput);
 
   // Attach security warnings to allow/warn results
@@ -2053,11 +3016,18 @@ async function runAsync(input) {
     }
   }
 
-  const behavioralContext = buildBehavioralContext();
-  const lessonContext = buildRelevantLessonContext(toolName, toolInput);
+  
+  const behavioralContext = safeSecretStorageWrite ? null : buildBehavioralContext();
+  const lessonContext = safeSecretStorageWrite ? null : await buildRelevantLessonContextAsync(toolName, toolInput);
+  
+  if (lessonContext && lessonContext.decision === "deny") {
+    return formatOutput(applyEnforcementPosture(lessonContext));
+  }
+  
   const recentContext = buildRecentCorrectiveActionsContext();
   const combinedContext = mergeContextStrings(lessonContext, recentContext, behavioralContext);
-  return formatOutput(result, combinedContext);
+  return formatOutput(applyEnforcementPosture(result), combinedContext);
+
 }
 
 function run(input) {
@@ -2074,6 +3044,13 @@ function run(input) {
 
   const toolName = input.tool_name || '';
   const toolInput = input.tool_input || {};
+  const safeSecretStorageWrite = isSafeSecretStorageWrite(toolName, toolInput, process.cwd());
+
+  const sequenceGuard = evaluateSequenceState(toolName, toolInput);
+  if (sequenceGuard && sequenceGuard.decision === 'deny') {
+    return formatOutput(applyEnforcementPosture(sequenceGuard));
+  }
+
   const result = evaluateGates(toolName, toolInput);
 
   // Attach security warnings to allow/warn results
@@ -2086,11 +3063,18 @@ function run(input) {
     }
   }
 
-  const behavioralContext = buildBehavioralContext();
-  const lessonContext = buildRelevantLessonContext(toolName, toolInput);
+  
+  const behavioralContext = safeSecretStorageWrite ? null : buildBehavioralContext();
+  const lessonContext = safeSecretStorageWrite ? null : buildRelevantLessonContext(toolName, toolInput);
+  
+  if (lessonContext && lessonContext.decision === "deny") {
+    return formatOutput(applyEnforcementPosture(lessonContext));
+  }
+  
   const recentContext = buildRecentCorrectiveActionsContext();
   const combinedContext = mergeContextStrings(lessonContext, recentContext, behavioralContext);
-  return formatOutput(result, combinedContext);
+  return formatOutput(applyEnforcementPosture(result), combinedContext);
+
 }
 
 // ---------------------------------------------------------------------------
@@ -2223,7 +3207,84 @@ function registerClaimGate(claimPattern, requiredActions, blockMessage) {
   return entry;
 }
 
-function verifyClaimEvidence(claimText) {
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return Array.from(new Set(
+    value
+      .map((item) => String(item || '').trim())
+      .filter(Boolean)
+  ));
+}
+
+function normalizeGoalContract(goalContract) {
+  if (!goalContract || typeof goalContract !== 'object' || Array.isArray(goalContract)) {
+    return null;
+  }
+
+  const goal = String(goalContract.goal || '').trim();
+  const doneWhen = normalizeStringArray(goalContract.doneWhen);
+  const requiredActions = normalizeStringArray(goalContract.proveBy);
+  const mustNotChange = normalizeStringArray(goalContract.mustNotChange);
+  const handoff = {
+    workerAgent: String(goalContract.workerAgent || '').trim() || null,
+    reviewerAgent: String(goalContract.reviewerAgent || '').trim() || null,
+    orchestratorAgent: String(goalContract.orchestratorAgent || '').trim() || null,
+  };
+
+  const matched = Boolean(
+    goal ||
+    doneWhen.length > 0 ||
+    requiredActions.length > 0 ||
+    mustNotChange.length > 0 ||
+    handoff.workerAgent ||
+    handoff.reviewerAgent ||
+    handoff.orchestratorAgent
+  );
+
+  if (!matched) return null;
+
+  return {
+    goal: goal || null,
+    doneWhen,
+    requiredActions,
+    mustNotChange,
+    handoff,
+  };
+}
+
+function evaluateGoalContract(goalContract, actions = loadSessionActions()) {
+  const normalized = normalizeGoalContract(goalContract);
+  if (!normalized) {
+    return {
+      matched: false,
+      passed: true,
+      goal: null,
+      doneWhen: [],
+      requiredActions: [],
+      missingActions: [],
+      mustNotChange: [],
+      handoff: {
+        workerAgent: null,
+        reviewerAgent: null,
+        orchestratorAgent: null,
+      },
+    };
+  }
+
+  const missingActions = normalized.requiredActions.filter((actionId) => !actions[actionId]);
+  return {
+    matched: true,
+    passed: missingActions.length === 0,
+    goal: normalized.goal,
+    doneWhen: normalized.doneWhen,
+    requiredActions: normalized.requiredActions,
+    missingActions,
+    mustNotChange: normalized.mustNotChange,
+    handoff: normalized.handoff,
+  };
+}
+
+function verifyClaimEvidence(claimText, options = {}) {
   const normalizedClaimText = String(claimText || '').trim();
   if (!normalizedClaimText) {
     throw new Error('claimText is required');
@@ -2251,9 +3312,23 @@ function verifyClaimEvidence(claimText) {
     });
   }
 
+  const goalContract = evaluateGoalContract(options.goalContract, actions);
+  if (goalContract.matched) {
+    checks.push({
+      claim: 'goal_contract',
+      passed: goalContract.passed,
+      missing: goalContract.missingActions,
+      message: goalContract.passed
+        ? 'Goal contract evidence present'
+        : `Goal contract requires evidence: ${goalContract.missingActions.join(', ')}`,
+      goalContract,
+    });
+  }
+
   return {
     verified: checks.every((check) => check.passed),
     checks,
+    goalContract,
   };
 }
 
@@ -2273,6 +3348,7 @@ module.exports = {
   setTaskScope,
   setBranchGovernance,
   approveProtectedAction,
+  breakGlassEmergency,
   getScopeState,
   getBranchGovernanceState,
   isConditionSatisfied,
@@ -2287,8 +3363,10 @@ module.exports = {
   matchesGate,
   evaluateGates,
   evaluateGatesAsync,
+  isAutonomousRun,
   computeExecutableHash,
   formatOutput,
+  isApprovalGatesEnabled,
   run,
   runAsync,
   trackAction,
@@ -2297,6 +3375,8 @@ module.exports = {
   clearSessionActions,
   loadClaimGates,
   registerClaimGate,
+  normalizeGoalContract,
+  evaluateGoalContract,
   verifyClaimEvidence,
   DEFAULT_CONFIG_PATH,
   DEFAULT_CLAIM_GATES_PATH,
@@ -2313,6 +3393,7 @@ module.exports = {
   buildBehavioralContext,
   buildRecentCorrectiveActionsContext,
   buildRelevantLessonContext,
+  buildRelevantLessonContextAsync,
   extractActionContext,
   extractAvoidanceAdvice,
   mergeContextStrings,
@@ -2324,10 +3405,20 @@ module.exports = {
   evaluateBoostedRiskTagGuard,
   registerPrThreadResolutionClaimGate,
   evaluatePendingPrThreadResolutionGate,
+  isReadOnlyObservabilityTool,
   getLocalOnlyScopeSources,
   isRemoteSideEffectCommand,
   evaluateLocalOnlyRemoteSideEffectGate,
+  recordHelperScriptWrite,
+  evaluateStatefulHelperBypassGate,
+  isAgentHookSettingsFile,
+  isBreakGlassSettingsRecoveryAction,
   PR_THREAD_RESOLUTION_ACTION,
+  HELPER_BYPASS_ACTION,
+  buildBlockActionProCta,
+  applyDailyBlockCap,
+  getTodayBlockCount,
+  incrementTodayBlockCount,
 };
 
 // ---------------------------------------------------------------------------