mpalpha · January 29, 2026 10:03
diff --git a/README.md b/README.md
diff --git a/check-protocol.cjs b/check-protocol.cjs
 #!/usr/bin/env node
 const fs = require('fs');
 const path = require('path');
 const os = require('os');

 // BUG #25 FIX: GC counter at FILE SCOPE (persists across tool calls)
 let gcCounter = 0;

 // Read stdin
 let input = '';
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
  // ┌─────────────────────────────────────────────────────────┐
  // │ EXEMPTIONS: Allow protocol tools without recursion      │
  // └─────────────────────────────────────────────────────────┘
  // Prevent infinite loop: these tools don't need to call themselves first
  try {
    const hookData = JSON.parse(input);
    const { tool_name } = hookData;

    // Exempt informed_reasoning and protocol-enforcer MCP tools
    const exemptedTools = [
      'mcp__memory-augmented-reasoning__informed_reasoning',
      'mcp__protocol-enforcer__verify_protocol_compliance',
      'mcp__protocol-enforcer__authorize_file_operation'
    ];

    if (exemptedTools.includes(tool_name)) {
      const response = {
        hookSpecificOutput: {
          hookEventName: "PreToolUse",
          permissionDecision: "allow",
          permissionDecisionReason: `✅ protocol-enforcer: ${tool_name} exempted (prevents infinite loop)`
        }
      };
      console.log(JSON.stringify(response));
      process.stderr.write(`✅ protocol-enforcer: ${tool_name} exempted\n`);
      process.exit(0);
    }
  } catch (e) {
    // Continue with token checks if JSON parsing fails
  }

  // BUG #5 FIX: Garbage collection (runs every 10 tool calls)
  gcCounter++;
  if (gcCounter % 10 === 0) {
    try {
      const homeDir = os.homedir();
      const files = fs.readdirSync(homeDir);
      const now = Date.now();
      let cleanedCount = 0;

      files.forEach(file => {
        if (file.startsWith('.protocol-session-') && file.endsWith('.json')) {
          // BUG #23 FIX: Skip temp files
          if (file.endsWith('.json.tmp')) return;

          const filePath = path.join(homeDir, file);
          try {
            const stats = fs.statSync(filePath);
            const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));

            // BUG #19 FIX: Use mtime as fallback
            const fileAge = now - (data.created_at || stats.mtimeMs);

            // Clean if expired or older than 24 hours
            if (data.expires_at < now || fileAge > 86400000) {
              fs.unlinkSync(filePath);
              cleanedCount++;
            }
          } catch (e) {
            // BUG #8 FIX: Delete malformed files
            try {
              fs.unlinkSync(filePath);
              cleanedCount++;
            } catch (deleteErr) {
              // Ignore deletion errors
            }
          }
        }
      });

      if (cleanedCount > 0) {
        process.stderr.write(`🗑️  protocol-enforcer: cleaned ${cleanedCount} expired token(s)\n`);
      }
    } catch (e) {
      // Ignore GC errors
    }
  }

  // ┌─────────────────────────────────────────────────────────┐
  // │ CHECK 3: Validate session token (if exists)            │
  // └─────────────────────────────────────────────────────────┘
  let hookData;
  try {
    hookData = JSON.parse(input);
  } catch (e) {
    // Already tried parsing above, just use empty object
    hookData = {};
  }

  // BUG #27/#28/#29 FIX: Scan directory for ANY valid session token
  // No need to know session_id in advance - just find any valid token
  try {
    const homeDir = os.homedir();
    const files = fs.readdirSync(homeDir);
    const now = Date.now();

    for (const file of files) {
      // Look for session token files (exclude temp files)
      if (file.startsWith('.protocol-session-') && file.endsWith('.json') && !file.endsWith('.tmp')) {
        const sessionTokenFile = path.join(homeDir, file);

        try {
          // BUG #1 FIX: Check token maturity (100ms minimum age)
          const stats = fs.statSync(sessionTokenFile);
          const tokenAge = now - stats.mtimeMs;

          if (tokenAge < 100) {
            // Token too young - skip and check next file
            continue;
          }

          // BUG #10 FIX: Validate token structure
          const tokenData = JSON.parse(fs.readFileSync(sessionTokenFile, 'utf8'));

          // Invalid structure - delete and continue
          if (!tokenData.session_id || !tokenData.expires_at || !tokenData.created_at) {
            try {
              fs.unlinkSync(sessionTokenFile);
            } catch (deleteErr) {
              // Ignore deletion errors
            }
            continue;
          }

          // Expired - delete and continue
          if (tokenData.expires_at < now) {
            try {
              fs.unlinkSync(sessionTokenFile);
            } catch (deleteErr) {
              // Ignore deletion errors
            }
            continue;
          }

          // Valid session token found - allow tool immediately
          const response = {
            hookSpecificOutput: {
              hookEventName: "PreToolUse",
              permissionDecision: "allow",
              permissionDecisionReason: "✅ protocol-enforcer: valid session token"
            }
          };
          console.log(JSON.stringify(response));
          process.stderr.write(`✅ All gates passed - session token valid\n`);
          process.exit(0);
        } catch (e) {
          // BUG #8 + #9 FIX: Handle read/parse errors - delete malformed token
          try {
            fs.unlinkSync(sessionTokenFile);
          } catch (deleteErr) {
            // Ignore deletion errors
          }
          // Continue scanning for other tokens
          continue;
        }
      }
    }
  } catch (e) {
    // Directory scan failed - log warning and continue to CHECK 1/CHECK 2
    process.stderr.write(`⚠️  protocol-enforcer: session token scan error - ${e.message}\n`);
  }

  // No valid session token - continue with CHECK 1 and CHECK 2

  const tokenFile = path.join(os.homedir(), '.protocol-enforcer-token');
  const reasoningTokenFile = path.join(os.homedir(), '.protocol-informed-reasoning-token');

  // ┌─────────────────────────────────────────────────────────┐
  // │ CHECK 1: Verify informed_reasoning was called           │
  // └─────────────────────────────────────────────────────────┘
  if (!fs.existsSync(reasoningTokenFile)) {
    const response = {
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: "⛔ protocol-enforcer: must call informed_reasoning (analyze phase) first"
      }
    };
    console.log(JSON.stringify(response));
    process.stderr.write('⛔ REASON gate blocking - call informed_reasoning first\n');
    process.exit(0);
  }

  // ┌─────────────────────────────────────────────────────────┐
  // │ CHECK 2: Verify protocol compliance authorization       │
  // └─────────────────────────────────────────────────────────┘
  if (!fs.existsSync(tokenFile)) {
    const response = {
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: "⛔ protocol-enforcer: call verify_protocol_compliance then authorize_file_operation"
      }
    };
    console.log(JSON.stringify(response));
    process.stderr.write('⛔ LEARN gate blocking - call search_experiences first\n');
    process.exit(0);
  }

  // Both tokens exist - consume them and allow
  try {
    fs.unlinkSync(reasoningTokenFile);
    fs.unlinkSync(tokenFile);

    const response = {
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "allow",
        permissionDecisionReason: "✅ protocol-enforcer: all requirements met"
      }
    };
    console.log(JSON.stringify(response));
    process.stderr.write('✅ All gates passed - operation authorized\n');
    process.exit(0);
  } catch (e) {
    const response = {
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: `⛔ protocol-enforcer: token error - ${e.message}`
      }
    };
    console.log(JSON.stringify(response));
    process.stderr.write(`\n⛔ protocol-enforcer: token consumption failed - ${e.message}\n`);
    process.exit(0);
  }
 });
diff --git a/config.behavioral.json b/config.behavioral.json
 {
  "enforced_rules": {
    "require_protocol_steps": [
      {
        "name": "sequential_thinking",
        "hook": "user_prompt_submit"
      },
      {
        "name": "analyze_behavior",
        "hook": "user_prompt_submit"
      },
      {
        "name": "apply_chores_fixes",
        "hook": "pre_tool_use"
      }
    ],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 5
  },
  "checklist_items": [
    {
      "text": "Sequential thinking completed FIRST",
      "hook": "user_prompt_submit"
    },
    {
      "text": "Behavioral patterns analyzed systematically",
      "hook": "user_prompt_submit"
    },
    {
      "text": "Constraint issues addressed (structure/format adherence)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Hallucination issues addressed (no false information)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Overconfidence issues addressed (uncertainty expressed when appropriate)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Reasoning issues addressed (logical consistency verified)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Technical precision maintained (state 'I don't know' when uncertain)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Zero deflection policy (attempt tools before claiming unavailable)",
      "hook": "pre_tool_use"
    },
    {
      "text": "No 'likely' explanations without verification",
      "hook": "pre_tool_use"
    },
    {
      "text": "Ethical/Safety issues addressed (harmful content prevented)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Sycophancy issues addressed (truthfulness over false agreement)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Professional objectivity maintained (facts over validation)",
      "hook": "post_tool_use"
    }
  ]
 }
diff --git a/config.development.json b/config.development.json
 {
  "enforced_rules": {
    "require_protocol_steps": [
      {
        "name": "sequential_thinking",
        "hook": "user_prompt_submit"
      },
      {
        "name": "task_initiation",
        "hook": "user_prompt_submit"
      },
      {
        "name": "pre_planning_analysis",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      },
      {
        "name": "plan_generation",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      }
    ],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 5
  },
  "checklist_items": [
    {
      "text": "Pre-response compliance audit completed",
      "hook": "user_prompt_submit"
    },
    {
      "text": "Sequential thinking completed FIRST (mcp__clear-thought__sequentialthinking)",
      "hook": "user_prompt_submit"
    },
    {
      "text": "User request restated with ALL ambiguities clarified",
      "hook": "user_prompt_submit"
    },
    {
      "text": "Requirements gathered (tickets, designs, data sources)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Existing patterns analyzed for reuse (components, hooks, utils)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Dependencies identified (files to modify/create, reusable code)",
      "hook": "pre_tool_use"
    },
    {
      "text": "PLAN comprehensive (objective, files, dependencies, tools, confidence, risks)",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "PLAN confirmed by user BEFORE executing code",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Technical precision maintained (no 'likely' explanations)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Pattern matching verified (file structure, naming, code style)",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Reuse verified (searched before creating)",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "TypeScript strict mode (no 'any' without justification)",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Linting passed",
      "hook": "post_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Type check passed",
      "hook": "post_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "No console.log() statements",
      "hook": "post_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Import order correct",
      "hook": "post_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Acceptance criteria verified",
      "hook": "post_tool_use"
    },
    {
      "text": "Completion summarized with deviations justified",
      "hook": "post_tool_use"
    }
  ]
 }
diff --git a/config.foundation.json b/config.foundation.json
 {
  "$schema": "https://raw.githubusercontent.com/mpalpha/protocol-enforcer-mcp/main/schema.json",
  "version": "2.0.0",
  "project_name": "Your Project Name",
  "description": "Foundation strategies - optimal balance of enforcement and efficiency",

  "strategies_enabled": {
    "session_tokens": true,
    "extended_enforcement": true,
    "macro_gates": true,
    "fast_track_mode": true,
    "unified_tokens": true
  },

  "security": {
    "session_token_ttl_ms": 600000,
    "session_token_ttl_description": "10 minutes (MCP recommended)",
    "allow_extended_ttl": false,
    "extended_ttl_warning": "Extended TTL (>10min) increases security risk. Only enable for trusted environments."
  },

  "automatic_experience_recording": {
    "enabled": true,
    "scope": "auto",
    "auto_discover_keywords": true,
    "project_keywords": [],
    "default_when_uncertain": "project",
    "trigger": "post_tool_use",
    "domains": ["Tools", "Protocol", "Debugging", "Decision"],
    "minimum_confidence": 0.7,
    "record_for_tools": ["Write", "Edit", "NotebookEdit", "WebSearch", "Grep"]
  },

  "enforced_rules": {
    "require_protocol_steps": [
      {
        "name": "informed_reasoning_analyze",
        "description": "Use informed_reasoning before ANY tool",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit", "NotebookEdit", "WebSearch", "Grep", "Task"]
      },
      {
        "name": "record_experience",
        "description": "Record experience after completing any task",
        "hook": "post_tool_use",
        "applies_to": ["Write", "Edit", "NotebookEdit", "WebSearch", "Grep", "Task"]
      }
    ],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 3,
    "blocking_mode": "strict"
  },

  "checklist_items": [
    {
      "text": "ANALYZE: Used informed_reasoning, clarified requirements, reviewed relevant documentation/designs (if applicable), searched codebase",
      "hook": "pre_tool_use",
      "category": "critical",
      "gate": "ANALYZE"
    },
    {
      "text": "PLAN: Analyzed dependencies, generated PLAN with confidence/risks, received user confirmation",
      "hook": "pre_tool_use",
      "category": "critical",
      "gate": "PLAN"
    },
    {
      "text": "VALIDATE: Ran build/lint/type-check, verified acceptance criteria, recorded experience",
      "hook": "post_tool_use",
      "category": "critical",
      "gate": "VALIDATE"
    }
  ],

  "fast_track_mode": {
    "enabled": true,
    "low_complexity_criteria": {
      "single_line_edits": true,
      "comment_only_changes": true,
      "string_literal_changes": true
    },
    "always_full_protocol": {
      "critical_paths": [
        ".env",
        ".cursor/hooks/",
        ".protocol-enforcer.json"
      ]
    }
  }
 }
diff --git a/config.minimal.json b/config.minimal.json
 {
  "enforced_rules": {
    "require_protocol_steps": [
      {
        "name": "sequential_thinking",
        "hook": "user_prompt_submit"
      },
      {
        "name": "planning",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      },
      {
        "name": "execution",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      }
    ],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 3
  },
  "checklist_items": [
    {
      "text": "Sequential thinking completed FIRST",
      "hook": "user_prompt_submit"
    },
    {
      "text": "Task requirements clarified with user",
      "hook": "pre_tool_use"
    },
    {
      "text": "Plan created and confirmed before execution",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Technical precision maintained (state 'I don't know' when uncertain)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Zero deflection policy (attempt available tools before claiming unavailable)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Completion verified against stated objectives",
      "hook": "post_tool_use",
      "applies_to": ["Write", "Edit"]
    }
  ]
 }
diff --git a/config.project-example.json b/config.project-example.json
 {
  "$schema": "https://raw.githubusercontent.com/mpalpha/protocol-enforcer-mcp/main/schema.json",
  "version": "1.0.0",
  "project_name": "SmartPass Admin UI",
  "description": "Protocol enforcement configuration for SmartPass Admin UI development workflow",

  "enforced_rules": {
    "require_protocol_steps": [
      {
        "name": "informed_reasoning_required",
        "description": "Use mcp__memory-augmented-reasoning__informed_reasoning (analyze phase) before ANY action - enforced at UserPromptSubmit level",
        "hook": "user_prompt_submit",
        "applies_to": []
      },
      {
        "name": "informed_reasoning_analyze",
        "description": "Use mcp__memory-augmented-reasoning__informed_reasoning (analyze phase) before ANY action to get context-aware guidance",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      },
      {
        "name": "clarify_requirements",
        "description": "Restate user request and identify all ambiguities",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      },
      {
        "name": "gather_requirements",
        "description": "Review Jira ticket, Figma designs, and existing codebase",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      },
      {
        "name": "analyze_dependencies",
        "description": "Identify files, components, hooks, utilities, and GraphQL operations",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      },
      {
        "name": "generate_plan",
        "description": "Create comprehensive PLAN with confidence level and risks",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      },
      {
        "name": "await_confirmation",
        "description": "Receive explicit PLAN confirmation from user before execution",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      }
    ],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 8,
    "blocking_mode": "strict"
  },

  "checklist_items": [
    {
      "text": "Used mcp__memory-augmented-reasoning__informed_reasoning (analyze phase) tool before proceeding",
      "hook": "pre_tool_use",
      "category": "critical"
    },
    {
      "text": "Identified and clarified all ambiguities in the request",
      "hook": "pre_tool_use",
      "category": "planning"
    },
    {
      "text": "Reviewed Jira ticket for acceptance criteria and technical notes (if applicable)",
      "hook": "pre_tool_use",
      "category": "requirements"
    },
    {
      "text": "Checked Figma designs for UI specifications and design tokens (if UI task)",
      "hook": "pre_tool_use",
      "category": "requirements"
    },
    {
      "text": "Searched src/components/ for reusable components",
      "hook": "pre_tool_use",
      "category": "codebase_analysis"
    },
    {
      "text": "Searched src/hooks/ for reusable custom hooks",
      "hook": "pre_tool_use",
      "category": "codebase_analysis"
    },
    {
      "text": "Searched src/utils/ for reusable utilities",
      "hook": "pre_tool_use",
      "category": "codebase_analysis"
    },
    {
      "text": "Analyzed existing GraphQL operations in src/graphql/operations/",
      "hook": "pre_tool_use",
      "category": "codebase_analysis"
    },
    {
      "text": "Verified no new dependencies needed (or requested authorization)",
      "hook": "pre_tool_use",
      "category": "dependencies"
    },
    {
      "text": "Generated comprehensive PLAN with task objective, files, tools, confidence level, risks, and scope statement",
      "hook": "pre_tool_use",
      "category": "planning"
    },
    {
      "text": "Received explicit PLAN confirmation from user",
      "hook": "pre_tool_use",
      "category": "critical"
    },
    {
      "text": "Verified scope minimized to explicit request only (no feature creep)",
      "hook": "pre_tool_use",
      "category": "scope"
    },
    {
      "text": "Matched existing file structure and naming conventions",
      "hook": "pre_tool_use",
      "category": "patterns"
    },
    {
      "text": "Followed existing code patterns from similar components",
      "hook": "pre_tool_use",
      "category": "patterns"
    },
    {
      "text": "Ran yarn graphql:codegen after GraphQL operation changes",
      "hook": "post_tool_use",
      "category": "verification"
    },
    {
      "text": "Ran yarn lint:all and fixed all ESLint errors",
      "hook": "post_tool_use",
      "category": "verification"
    },
    {
      "text": "Ran yarn type-check and fixed all TypeScript errors",
      "hook": "post_tool_use",
      "category": "verification"
    },
    {
      "text": "Removed all console.log() statements",
      "hook": "post_tool_use",
      "category": "code_quality"
    },
    {
      "text": "Removed unnecessary code comments (self-documenting code preferred)",
      "hook": "post_tool_use",
      "category": "code_quality"
    },
    {
      "text": "Verified against acceptance criteria",
      "hook": "post_tool_use",
      "category": "validation"
    },
    {
      "text": "Checked development-checklists.md for pattern compliance",
      "hook": "post_tool_use",
      "category": "validation"
    }
  ],

  "behavioral_requirements": {
    "MODEL_framework": {
      "description": "Behavioral corrections framework from backup rules",
      "categories": [
        {
          "name": "constraint_adherence",
          "violations": [
            "Adding features beyond explicit request",
            "Refactoring code not requested",
            "Optimizing prematurely",
            "Adding error handling for impossible scenarios",
            "Creating abstractions for one-time operations"
          ]
        },
        {
          "name": "hallucination_prevention",
          "violations": [
            "Assuming code exists without reading files",
            "Guessing file paths or API endpoints",
            "Making up TypeScript types",
            "Fabricating design token values",
            "Inventing GraphQL operations without checking"
          ]
        },
        {
          "name": "overconfidence_reduction",
          "violations": [
            "Proceeding without user confirmation on PLAN",
            "Not stating 'I don't know' when uncertain",
            "Providing 'likely' explanations without verification",
            "Not requesting clarification on ambiguities"
          ]
        },
        {
          "name": "reasoning_transparency",
          "violations": [
            "Not explaining confidence level in PLAN",
            "Not documenting risks identified",
            "Not stating scope boundaries explicitly",
            "Not justifying deviations from PLAN"
          ]
        },
        {
          "name": "ethical_alignment",
          "violations": [
            "Hardcoding credentials in configuration",
            "Committing sensitive tokens to version control",
            "Not warning about security risks"
          ]
        }
      ]
    }
  },

  "custom_rules": {
    "scss_styling": {
      "pre_tool_use": [
        "CSS module class names use camelCase (e.g., .passTypeCard)",
        "All spacing uses rem units on 2px/4px grid",
        "Font styling uses $font-* variables (not font-weight)",
        "Use @use instead of deprecated @import",
        "Use react-md CSS variables for react-md components"
      ],
      "post_tool_use": [
        "Run yarn stylelint:fix",
        "No unnecessary CSS comments",
        "Border-radius uses .5rem (8px) not 7px"
      ]
    },
    "typescript_react": {
      "pre_tool_use": [
        "Component props defined inline (not separate .types.ts)",
        "No React.FC or FC type annotations",
        "Import order: React, third-party, components, hooks, utils, GraphQL, types, styles (last)",
        "Use type keyword for all type-only imports"
      ],
      "post_tool_use": [
        "Run yarn eslint:fix",
        "Run yarn type-check",
        "Remove unused imports",
        "Props alphabetized (callbacks after regular props)"
      ]
    },
    "graphql": {
      "pre_tool_use": [
        "NO exports in src/graphql/operations/ files",
        "Use gql(...) without export const"
      ],
      "post_tool_use": [
        "Run yarn graphql:codegen after operation changes",
        "Import from src/graphql/generated/graphql only",
        "Alias all useQuery/useMutation return values"
      ]
    }
  },

  "tool_permissions": {
    "auto_approved_tools": [
      "yarn graphql:codegen",
      "yarn lint:all",
      "yarn eslint:fix",
      "yarn stylelint:fix",
      "yarn type-check",
      "Bash",
      "Read",
      "Glob",
      "Grep"
    ],
    "require_user_approval": [
      "yarn add",
      "yarn remove",
      "git push",
      "rm -rf",
      "Write",
      "Edit"
    ]
  },

  "documentation": {
    "references": [
      ".cursor/development-checklists.md",
      ".cursor/rules/mandatory-supervisor-protocol.mdc",
      ".cursor/rules/styling.mdc",
      ".cursor/rules/typescript.mdc",
      ".cursor/rules/graphql.mdc",
      "CLAUDE.md"
    ],
    "mcp_servers_required": [
      "mcp__memory-augmented-reasoning__informed_reasoning",
      "mcp__memory-bank__*",
      "mcp__mcp-atlassian__jira_get_issue",
      "mcp__figma__get_design_context"
    ]
  }
 }
diff --git a/index.js b/index.js
 #!/usr/bin/env node

 /**
 * Protocol Enforcer MCP Server
 * Enforces custom workflow protocol compliance before allowing file operations
 *
 * Version: 3.0.1
 * Author: Jason Lusk <[email protected]>
 * License: MIT
 */

 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const readline = require('readline');
 const crypto = require('crypto');

 const VERSION = '3.0.1';

 // Custom error class for parameter validation (returns -32602 instead of -32603)
 class ValidationError extends Error {
  constructor(message) {
    super(message);
    this.name = 'ValidationError';
    this.code = -32602; // Invalid params
  }
 }

 // State tracking
 const state = {
  configPath: null,
  config: null,
  complianceChecks: [],
  operationTokens: new Map(), // Map<token, {expires: timestamp, used: boolean}>
  tokenTimeout: 60000, // 60 seconds
  sessionTokens: new Map(), // Map<sessionId, {expires: timestamp, created: timestamp}>
  sessionTokenTimeout: 3600000, // 60 minutes
  toolLogPath: path.join(os.homedir(), '.protocol-tool-log.json')
 };

 // BUG #20 FIX: Background cleanup of expired session tokens (every 5 minutes)
 setInterval(() => {
  const now = Date.now();
  for (const [sessionId, tokenData] of state.sessionTokens.entries()) {
    if (tokenData.expires < now) {
      state.sessionTokens.delete(sessionId);
      // Clean up file system token
      const tokenFile = path.join(os.homedir(), `.protocol-session-${sessionId}.json`);
      try {
        fs.unlinkSync(tokenFile);
      } catch (err) {
        // Ignore errors - file may already be cleaned by GC
      }
    }
  }
 }, 300000); // 5 minutes

 // Tool execution tracking functions
 function readToolLog() {
  try {
    if (fs.existsSync(state.toolLogPath)) {
      const data = fs.readFileSync(state.toolLogPath, 'utf8');
      return JSON.parse(data);
    }
  } catch (err) {
    console.error('[protocol-enforcer] Error reading tool log:', err.message);
  }
  return [];
 }

 function writeToolLog(log) {
  try {
    fs.writeFileSync(state.toolLogPath, JSON.stringify(log, null, 2), 'utf8');
  } catch (err) {
    console.error('[protocol-enforcer] Error writing tool log:', err.message);
  }
 }

 function recordToolExecution(toolName, parameters = {}) {
  const log = readToolLog();
  log.push({
    sessionId: process.env.CLAUDE_SESSION_ID || 'unknown',
    toolName,
    parameters,
    timestamp: new Date().toISOString()
  });
  writeToolLog(log);
 }

 function getSessionToolCalls(sessionId) {
  const log = readToolLog();
  return log.filter(entry => entry.sessionId === sessionId);
 }

 // Default configuration (MODEL Framework CHORES behavioral fixes)
 const DEFAULT_CONFIG = {
  enforced_rules: {
    require_protocol_steps: [
      {
        name: "analyze_behavior",
        hook: "user_prompt_submit"
      },
      {
        name: "apply_chores_fixes",
        hook: "pre_tool_use",
        applies_to: ["Write", "Edit"]
      }
    ],
    require_checklist_confirmation: true,
    minimum_checklist_items: 3
  },
  checklist_items: [
    {
      text: "Constraint issues addressed (structure/format adherence)",
      hook: "pre_tool_use"
    },
    {
      text: "Hallucination issues addressed (no false information)",
      hook: "pre_tool_use"
    },
    {
      text: "Overconfidence issues addressed (uncertainty expressed when appropriate)",
      hook: "pre_tool_use"
    },
    {
      text: "Reasoning issues addressed (logical consistency verified)",
      hook: "pre_tool_use"
    },
    {
      text: "Ethical/Safety issues addressed (harmful content prevented)",
      hook: "pre_tool_use"
    },
    {
      text: "Sycophancy issues addressed (truthfulness over false agreement)",
      hook: "pre_tool_use"
    }
  ]
 };

 // Find config file (project scope takes precedence)
 function findConfigFile() {
  const cwd = process.cwd();
  const projectConfig = path.join(cwd, '.protocol-enforcer.json');
  const homeConfig = path.join(process.env.HOME || process.env.USERPROFILE, '.protocol-enforcer.json');

  if (fs.existsSync(projectConfig)) {
    return projectConfig;
  }
  if (fs.existsSync(homeConfig)) {
    return homeConfig;
  }
  return null;
 }

 // Load configuration
 function loadConfig() {
  const configPath = findConfigFile();
  if (configPath) {
    state.configPath = configPath;
    const rawConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
    state.config = validateConfig(rawConfig);
    return state.config;
  }
  state.config = DEFAULT_CONFIG;
  return null;
 }

 // Tool: initialize_protocol_config
 async function initializeProtocolConfig(args) {
  const scope = args.scope || 'project';

  let configPath;
  if (scope === 'project') {
    configPath = path.join(process.cwd(), '.protocol-enforcer.json');
  } else if (scope === 'user') {
    configPath = path.join(process.env.HOME || process.env.USERPROFILE, '.protocol-enforcer.json');
  } else {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ error: 'Invalid scope. Must be "project" or "user".' }, null, 2)
      }]
    };
  }

  if (fs.existsSync(configPath)) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          error: 'Configuration file already exists',
          path: configPath
        }, null, 2)
      }]
    };
  }

  fs.writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2), 'utf8');
  state.configPath = configPath;
  state.config = DEFAULT_CONFIG;

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        success: true,
        message: `Configuration file created at ${configPath}`,
        config: DEFAULT_CONFIG
      }, null, 2)
    }]
  };
 }

 // Validate config format
 function validateConfig(config) {
  const errors = [];

  // Validate protocol steps
  if (config.enforced_rules.require_protocol_steps) {
    config.enforced_rules.require_protocol_steps.forEach((step, idx) => {
      if (typeof step === 'string') {
        errors.push(`Protocol step at index ${idx} is a string. Must be an object with 'name' and 'hook' properties.`);
      } else if (!step.name || !step.hook) {
        errors.push(`Protocol step at index ${idx} missing required 'name' or 'hook' property.`);
      }
    });
  }

  // Validate checklist items
  if (config.checklist_items) {
    config.checklist_items.forEach((item, idx) => {
      if (typeof item === 'string') {
        errors.push(`Checklist item at index ${idx} is a string. Must be an object with 'text' and 'hook' properties.`);
      } else if (!item.text || !item.hook) {
        errors.push(`Checklist item at index ${idx} missing required 'text' or 'hook' property.`);
      }
    });
  }

  if (errors.length > 0) {
    throw new Error(`Invalid configuration format:\n${errors.join('\n')}\n\nSee README.md Configuration Reference section for correct format.`);
  }

  return config;
 }

 // Filter rules by hook and tool name
 function filterByHook(items, hook, toolName = null) {
  return items.filter(item => {
    // Check if hook matches
    if (item.hook !== hook) return false;

    // Check if tool-specific filtering applies
    if (item.applies_to && toolName) {
      return item.applies_to.includes(toolName);
    }

    return true;
  });
 }

 // ┌─────────────────────────────────────────────────────────────────────────┐
 // │ PHASE 3: Fast-Track Mode - Classify task complexity                    │
 // └─────────────────────────────────────────────────────────────────────────┘
 function classifyTaskComplexity(config, toolName, args = {}) {
  // Fast-track disabled - always use full protocol
  if (!config.fast_track_mode || !config.fast_track_mode.enabled) {
    return { fastTrackEligible: false, reason: 'Fast-track mode disabled' };
  }

  const criteria = config.fast_track_mode.low_complexity_criteria || {};
  const criticalPaths = config.fast_track_mode.always_full_protocol?.critical_paths || [];

  // Check if file is in critical paths (always requires full protocol)
  const filePath = args.file_path || args.path || '';
  if (filePath && criticalPaths.some(path => filePath.includes(path))) {
    return { fastTrackEligible: false, reason: `Critical path: ${filePath}` };
  }

  // Analyze complexity based on criteria
  let isLowComplexity = false;
  let matchedCriteria = null;

  // Single-line edits
  if (criteria.single_line_edits && args.old_string && args.new_string) {
    const oldLines = args.old_string.split('\n').length;
    const newLines = args.new_string.split('\n').length;
    if (oldLines === 1 && newLines === 1) {
      isLowComplexity = true;
      matchedCriteria = 'single_line_edits';
    }
  }

  // Comment-only changes
  if (criteria.comment_only_changes && args.old_string && args.new_string) {
    const commentPattern = /^\s*(\/\/|\/\*|\*|#)/;
    const oldIsComment = args.old_string.split('\n').every(line => !line.trim() || commentPattern.test(line));
    const newIsComment = args.new_string.split('\n').every(line => !line.trim() || commentPattern.test(line));
    if (oldIsComment || newIsComment) {
      isLowComplexity = true;
      matchedCriteria = 'comment_only_changes';
    }
  }

  // String literal changes
  if (criteria.string_literal_changes && args.old_string && args.new_string) {
    const stringPattern = /^[\s'"]+|[\s'"]+$/g;
    const oldCore = args.old_string.replace(stringPattern, '');
    const newCore = args.new_string.replace(stringPattern, '');
    // If structure is identical except for string content
    if (oldCore.length > 0 && newCore.length > 0 &&
        args.old_string.split('"').length === args.new_string.split('"').length) {
      isLowComplexity = true;
      matchedCriteria = 'string_literal_changes';
    }
  }

  return {
    fastTrackEligible: isLowComplexity,
    reason: isLowComplexity ? `Low complexity: ${matchedCriteria}` : 'Standard complexity - requires full protocol'
  };
 }

 // Tool: verify_protocol_compliance
 async function verifyProtocolCompliance(args) {
  const rawConfig = state.config || loadConfig() || DEFAULT_CONFIG;

  // Validate config format (throws if invalid)
  const config = validateConfig(rawConfig);
  const violations = [];

  const hook = args.hook;
  const toolName = args.tool_name || null;

  if (!hook) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          error: 'Missing required parameter: hook. Must specify which hook is calling (e.g., "user_prompt_submit", "pre_tool_use", "post_tool_use").'
        }, null, 2)
      }]
    };
  }

  // ┌─────────────────────────────────────────────────────────────────────────┐
  // │ PHASE 3: Fast-Track Mode - Check if task qualifies for fast-track     │
  // └─────────────────────────────────────────────────────────────────────────┘
  const fastTrackResult = classifyTaskComplexity(config, toolName, args);
  const isFastTrack = fastTrackResult.fastTrackEligible;

  // Check required protocol steps (filtered by hook)
  if (config.enforced_rules.require_protocol_steps && Array.isArray(config.enforced_rules.require_protocol_steps)) {
    const allRequiredSteps = config.enforced_rules.require_protocol_steps;
    const hookFilteredSteps = filterByHook(allRequiredSteps, hook, toolName);
    const completedSteps = args.protocol_steps_completed || [];

    const missingSteps = hookFilteredSteps.filter(step => !completedSteps.includes(step.name));
    if (missingSteps.length > 0) {
      missingSteps.forEach(step => {
        violations.push(`VIOLATION: Required protocol step not completed: ${step.name} (hook: ${hook})`);
      });
    }
  }

  // Check checklist confirmation (filtered by hook)
  if (config.enforced_rules.require_checklist_confirmation) {
    const checkedItems = args.checklist_items_checked || [];
    const allRequiredItems = config.checklist_items || [];
    const hookFilteredItems = filterByHook(allRequiredItems, hook, toolName);
    const minItems = config.enforced_rules.minimum_checklist_items || 0;

    // Count only items applicable to this hook
    // Fast-track: Reduce minimum by 1 if PLAN gate is skipped
    let applicableMinItems = Math.min(minItems, hookFilteredItems.length);
    if (isFastTrack) {
      const planGateItems = hookFilteredItems.filter(item => item.gate === 'PLAN');
      applicableMinItems = Math.max(0, applicableMinItems - planGateItems.length);
    }

    if (checkedItems.length < applicableMinItems) {
      violations.push(`VIOLATION: Only ${checkedItems.length} checklist items checked, minimum ${applicableMinItems} required for hook '${hook}'`);
    }

    // Filter out PLAN gate items if fast-track eligible
    let uncheckedRequired = hookFilteredItems.filter(item => !checkedItems.includes(item.text));
    if (isFastTrack) {
      uncheckedRequired = uncheckedRequired.filter(item => item.gate !== 'PLAN');
    }
    if (uncheckedRequired.length > 0) {
      violations.push(`VIOLATION: Required checklist items not confirmed for hook '${hook}': ${uncheckedRequired.map(i => i.text).join(', ')}`);
    }

    // ┌─────────────────────────────────────────────────────────────────────────┐
    // │ PHASE 2: Macro-Gates - Gate-level validation                           │
    // └─────────────────────────────────────────────────────────────────────────┘
    // Group checklist items by gate (if gate field exists)
    const gateGroups = {};
    hookFilteredItems.forEach(item => {
      if (item.gate) {
        if (!gateGroups[item.gate]) {
          gateGroups[item.gate] = { items: [], checked: [] };
        }
        gateGroups[item.gate].items.push(item.text);
        if (checkedItems.includes(item.text)) {
          gateGroups[item.gate].checked.push(item.text);
        }
      }
    });

    // Validate gate completion (all items in a gate must be checked)
    // Fast-track mode: skip PLAN gate validation for low-complexity tasks
    Object.keys(gateGroups).forEach(gateName => {
      // Skip PLAN gate if fast-track eligible
      if (isFastTrack && gateName === 'PLAN') {
        return;
      }

      const gate = gateGroups[gateName];
      if (gate.checked.length < gate.items.length) {
        const uncheckedInGate = gate.items.filter(item => !gate.checked.includes(item));
        violations.push(`VIOLATION: Gate '${gateName}' incomplete - missing: ${uncheckedInGate.join(', ')}`);
      }
    });

    // ┌─────────────────────────────────────────────────────────────────────────┐
    // │ PHASE 4: Cross-reference checklist claims against actual tool calls    │
    // └─────────────────────────────────────────────────────────────────────────┘
    // Get session ID from most recent tool log entry (all tools in current session share same ID)
    const toolLog = readToolLog();
    const sessionId = toolLog.length > 0 ? toolLog[toolLog.length - 1].sessionId : 'unknown';
    const sessionTools = getSessionToolCalls(sessionId);

    // Helper: Check if any tool matching pattern was called
    const hasToolCall = (pattern) => {
      return sessionTools.some(call => {
        const toolName = call.toolName || '';
        return toolName.toLowerCase().includes(pattern.toLowerCase());
      });
    };

    /**
     * Determines if a checklist item is conditional (only applies in certain scenarios)
     *
     * Conditional items include qualifiers like:
     * - "(if applicable)" - Only required when relevant to the task
     * - "(if UI task)" - Only required for UI/design work
     * - "(if [condition])" - General conditional pattern
     * - "(when [condition])" - Alternative conditional pattern
     * - "(optional)" - Explicitly optional
     *
     * @param {string} itemText - The checklist item text
     * @returns {boolean} - True if item has conditional qualifier
     */
    const isConditionalItem = (itemText) => {
      const text = itemText.toLowerCase();
      return (
        text.includes('(if applicable)') ||
        text.includes('(if ui task)') ||
        text.includes('(if ') ||
        text.includes('(when ') ||
        text.includes('(optional)')
      );
    };

    // Verify search claims
    const searchClaims = checkedItems.filter(item =>
      item.toLowerCase().includes('search') ||
      item.toLowerCase().includes('check') && item.toLowerCase().includes('src/')
    );
    if (searchClaims.length > 0) {
      const hasSearch = hasToolCall('glob') || hasToolCall('grep');
      if (!hasSearch) {
        violations.push(
          `VIOLATION: Claimed searches (${searchClaims.length} items) but no Glob/Grep tool calls detected in session. ` +
          `Checklist requires actual tool execution, not assumptions.`
        );
      }
    }

    // Verify Jira review claims
    const jiraClaims = checkedItems.filter(item => {
      // Skip enforcement for conditional items (e.g., "if applicable")
      if (isConditionalItem(item)) {
        return false;
      }
      const text = item.toLowerCase();
      return text.includes('jira') || text.includes('ticket') || text.includes('acceptance criteria');
    });
    if (jiraClaims.length > 0) {
      const hasJira = hasToolCall('jira');
      if (!hasJira) {
        violations.push(
          `VIOLATION: Claimed Jira review but no jira tool calls detected in session. ` +
          `Must actually fetch ticket details, not assume requirements.`
        );
      }
    }

    // Verify Figma design claims
    const figmaClaims = checkedItems.filter(item => {
      // Skip enforcement for conditional items (e.g., "if UI task")
      if (isConditionalItem(item)) {
        return false;
      }
      const text = item.toLowerCase();
      return text.includes('figma') || (text.includes('design') && text.includes('ui'));
    });
    if (figmaClaims.length > 0) {
      const hasFigma = hasToolCall('figma');
      if (!hasFigma) {
        violations.push(
          `VIOLATION: Claimed Figma design review but no figma tool calls detected in session. ` +
          `Must actually fetch designs, not assume specifications.`
        );
      }
    }
  }

  // ┌─────────────────────────────────────────────────────────────────────────┐
  // │ Experience Search Enforcement - Verify suggested searches are executed │
  // └─────────────────────────────────────────────────────────────────────────┘
  if (hook === 'pre_tool_use') {
    const searchTokenPath = path.join(os.homedir(), '.protocol-search-required-token');

    if (fs.existsSync(searchTokenPath)) {
      try {
        const token = JSON.parse(fs.readFileSync(searchTokenPath, 'utf8'));
        const age = Date.now() - token.timestamp;

        // Only enforce if token is recent (< 5 minutes)
        if (age < 300000) {
          violations.push(
            `VIOLATION: informed_reasoning suggested searching experiences (query: "${token.suggestedQuery}"), but search_experiences was not called. You must search past learnings before proceeding.`
          );
        }
      } catch (e) {
        // Invalid token, ignore
      }
    }
  }

  // Record check
  state.complianceChecks.push({
    timestamp: new Date().toISOString(),
    passed: violations.length === 0,
    violations: violations,
    args: args
  });

  if (violations.length > 0) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          compliant: false,
          violations: violations,
          message: 'Protocol compliance check FAILED. Fix violations before proceeding.'
        }, null, 2)
      }]
    };
  }

  // Generate single-use operation token
  const crypto = require('crypto');
  const token = crypto.randomBytes(32).toString('hex');
  const expires = Date.now() + state.tokenTimeout;

  state.operationTokens.set(token, { expires, used: false });

  // Clean up expired tokens
  for (const [key, value] of state.operationTokens.entries()) {
    if (value.expires < Date.now() || value.used) {
      state.operationTokens.delete(key);
    }
  }

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        compliant: true,
        operation_token: token,
        token_expires_in_seconds: state.tokenTimeout / 1000,
        message: 'Protocol compliance verified. Use the operation_token with authorize_file_operation before proceeding.'
      }, null, 2)
    }]
  };
 }

 // Tool: get_compliance_status
 async function getComplianceStatus() {
  const recentChecks = state.complianceChecks.slice(-10);
  const passedCount = recentChecks.filter(c => c.passed).length;
  const failedCount = recentChecks.length - passedCount;

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        total_checks: state.complianceChecks.length,
        recent_checks: recentChecks.length,
        passed: passedCount,
        failed: failedCount,
        recent_violations: recentChecks
          .filter(c => !c.passed)
          .map(c => ({ timestamp: c.timestamp, violations: c.violations }))
      }, null, 2)
    }]
  };
 }

 // Tool: get_protocol_config
 async function getProtocolConfig() {
  const config = state.config || loadConfig() || DEFAULT_CONFIG;

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        config_path: state.configPath || 'Using default configuration',
        config: config
      }, null, 2)
    }]
  };
 }

 // ┌─────────────────────────────────────────────────────────────────────────┐
 // │ PHASE 4: Unified Token Model - Helper functions                        │
 // └─────────────────────────────────────────────────────────────────────────┘
 function isUnifiedTokensEnabled(config) {
  return config.strategies_enabled && config.strategies_enabled.unified_tokens === true;
 }

 function createUnifiedToken(sessionId, operationToken, ttlMs) {
  const now = Date.now();
  const tokenId = crypto.randomUUID();

  return {
    id: tokenId,
    session_id: sessionId,
    operation_token: operationToken,
    created_at: now,
    expires_at: now + ttlMs,
    version: '2.0'
  };
 }

 function writeUnifiedToken(sessionId, tokenData) {
  const tokenFile = path.join(os.homedir(), `.protocol-unified-${sessionId}.json`);
  const tempFile = `${tokenFile}.tmp`;

  try {
    fs.writeFileSync(tempFile, JSON.stringify(tokenData, null, 2), 'utf8');
    fs.renameSync(tempFile, tokenFile);
    return { success: true, filePath: tokenFile };
  } catch (err) {
    // Cleanup temp file on error
    try {
      fs.unlinkSync(tempFile);
    } catch (cleanupErr) {
      // Ignore cleanup errors
    }
    return { success: false, error: err.message };
  }
 }

 function readUnifiedToken(sessionId) {
  const unifiedFile = path.join(os.homedir(), `.protocol-unified-${sessionId}.json`);
  const legacySessionFile = path.join(os.homedir(), `.protocol-session-${sessionId}.json`);
  const legacyOperationFile = path.join(os.homedir(), '.protocol-enforcer-token');

  // Try unified token first
  if (fs.existsSync(unifiedFile)) {
    try {
      const content = fs.readFileSync(unifiedFile, 'utf8');
      const tokenData = JSON.parse(content);

      // Validate structure
      if (tokenData.session_id === sessionId && tokenData.expires_at > Date.now()) {
        return { found: true, type: 'unified', data: tokenData };
      }
    } catch (err) {
      // Invalid unified token, fall through to legacy
    }
  }

  // Fallback to legacy tokens
  let sessionToken = null;
  let operationToken = null;

  if (fs.existsSync(legacySessionFile)) {
    try {
      const content = fs.readFileSync(legacySessionFile, 'utf8');
      sessionToken = JSON.parse(content);
    } catch (err) {
      // Invalid session token
    }
  }

  if (fs.existsSync(legacyOperationFile)) {
    try {
      operationToken = fs.readFileSync(legacyOperationFile, 'utf8').trim();
    } catch (err) {
      // Invalid operation token
    }
  }

  if (sessionToken || operationToken) {
    return {
      found: true,
      type: 'legacy',
      data: { session: sessionToken, operation: operationToken }
    };
  }

  return { found: false };
 }

 // Tool: authorize_file_operation
 async function authorizeFileOperation(args) {
  const token = args.operation_token;
  const sessionId = args.session_id;

  if (!token) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          authorized: false,
          error: 'No operation token provided. You must call verify_protocol_compliance first to obtain a token.'
        }, null, 2)
      }]
    };
  }

  const tokenData = state.operationTokens.get(token);

  if (!tokenData) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          authorized: false,
          error: 'Invalid or expired operation token. Call verify_protocol_compliance again to obtain a new token.'
        }, null, 2)
      }]
    };
  }

  if (tokenData.used) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          authorized: false,
          error: 'Operation token already used. Each token is single-use only. Call verify_protocol_compliance again.'
        }, null, 2)
      }]
    };
  }

  if (tokenData.expires < Date.now()) {
    state.operationTokens.delete(token);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          authorized: false,
          error: 'Operation token expired. Call verify_protocol_compliance again to obtain a new token.'
        }, null, 2)
      }]
    };
  }

  // Mark token as used
  tokenData.used = true;

  // Write token file for PreToolUse hook verification
  // Token expires after 60 seconds to support parallel tool execution (Issue #3 fix)
  const tokenFile = path.join(os.homedir(), '.protocol-enforcer-token');
  try {
    const now = new Date();
    const expires = new Date(now.getTime() + 60000); // 60 seconds
    fs.writeFileSync(tokenFile, JSON.stringify({
      token: token,
      timestamp: now.toISOString(),
      expires: expires.toISOString()
    }), 'utf8');
  } catch (err) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          authorized: false,
          error: `Failed to write token file: ${err.message}`
        }, null, 2)
      }]
    };
  }

  // Handle session token creation if session_id provided
  if (sessionId && typeof sessionId === 'string' && sessionId.trim() !== '') {
    const now = Date.now();
    const expires = now + state.sessionTokenTimeout;
    const config = state.config || loadConfig() || DEFAULT_CONFIG;

    // ┌─────────────────────────────────────────────────────────────────────────┐
    // │ PHASE 4: Check if unified tokens are enabled                           │
    // └─────────────────────────────────────────────────────────────────────────┘
    if (isUnifiedTokensEnabled(config)) {
      // Create unified token (combines operation + session into one file)
      const unifiedTokenData = createUnifiedToken(sessionId, token, state.sessionTokenTimeout);
      const writeResult = writeUnifiedToken(sessionId, unifiedTokenData);

      if (writeResult.success) {
        // Store in memory
        state.sessionTokens.set(sessionId, {
          expires: unifiedTokenData.expires_at,
          created: unifiedTokenData.created_at,
          unified: true
        });

        return {
          content: [{
            type: 'text',
            text: JSON.stringify({
              authorized: true,
              session_token_created: true,
              token_type: 'unified',
              session_id: sessionId,
              session_expires_in_seconds: state.sessionTokenTimeout / 1000,
              message: 'File operation authorized. Unified session token created for 60-minute workflow.'
            }, null, 2)
          }]
        };
      } else {
        // Unified token creation failed, fall back to legacy
        // Continue with legacy token creation below
      }
    }

    // Legacy token creation (used when unified tokens disabled OR unified write failed)
    const sessionTokenFile = path.join(os.homedir(), `.protocol-session-${sessionId}.json`);

    // Check if session token already exists in memory
    let existingToken = state.sessionTokens.get(sessionId);

    if (existingToken && existingToken.expires > now) {
      // BUG #21 FIX: Verify file exists, recreate if missing (memory-file desync)
      if (!fs.existsSync(sessionTokenFile)) {
        const tokenData = {
          session_id: sessionId,
          created_at: existingToken.created,
          expires_at: existingToken.expires
        };

        // BUG #1 + #2 FIX: Atomic write (temp + rename)
        const tempFile = `${sessionTokenFile}.tmp`;
        try {
          fs.writeFileSync(tempFile, JSON.stringify(tokenData), 'utf8');
          fs.renameSync(tempFile, sessionTokenFile);
        } catch (err) {
          // Cleanup temp file on error
          try {
            fs.unlinkSync(tempFile);
          } catch (cleanupErr) {
            // Ignore cleanup errors
          }
          // Don't fail - memory token still valid, file will be recreated next time
        }
      }

      // Session token already valid
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            authorized: true,
            session_token_created: false,
            session_id: sessionId,
            session_expires_in_seconds: Math.round((existingToken.expires - now) / 1000),
            message: 'File operation authorized. Existing session token still valid.'
          }, null, 2)
        }]
      };
    }

    // Create new session token
    const tokenData = {
      session_id: sessionId,
      created_at: now,
      expires_at: expires
    };

    // BUG #1 + #2 FIX: Atomic write (temp + rename)
    const tempFile = `${sessionTokenFile}.tmp`;
    try {
      fs.writeFileSync(tempFile, JSON.stringify(tokenData), 'utf8');
      fs.renameSync(tempFile, sessionTokenFile);

      // Store in memory
      state.sessionTokens.set(sessionId, {
        expires: expires,
        created: now
      });

      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            authorized: true,
            session_token_created: true,
            session_id: sessionId,
            session_expires_in_seconds: state.sessionTokenTimeout / 1000,
            message: '✅ Session token created - proceed with informed_reasoning phases.\nUSER REQUIREMENT: Complete all 4 phases so the system learns from this task.'
          }, null, 2)
        }]
      };
    } catch (err) {
      // Cleanup temp file on error
      try {
        fs.unlinkSync(tempFile);
      } catch (cleanupErr) {
        // Ignore cleanup errors
      }

      // Session token creation failed, but single-use token file already written
      // Return success but warn about session token failure
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            authorized: true,
            session_token_created: false,
            session_id: sessionId,
            warning: `Failed to create session token: ${err.message}. Single-use token still valid.`,
            message: 'File operation authorized. Token file written for hook verification. You may now proceed with Write/Edit operations.'
          }, null, 2)
        }]
      };
    }
  }

  // No session_id provided - single-use token only
  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        authorized: true,
        session_token_created: false,
        message: 'File operation authorized. Token file written for hook verification. You may now proceed with Write/Edit operations.'
      }, null, 2)
    }]
  };
 }

 // MCP Protocol Handler
 const tools = [
  {
    name: 'initialize_protocol_config',
    description: 'Create a new protocol enforcer configuration file at project or user scope',
    inputSchema: {
      type: 'object',
      properties: {
        scope: {
          type: 'string',
          enum: ['project', 'user'],
          description: 'Where to create the config file: "project" (.protocol-enforcer.json in current directory) or "user" (~/.protocol-enforcer.json)'
        }
      },
      required: ['scope']
    }
  },
  {
    name: 'verify_protocol_compliance',
    description: 'Verify that mandatory protocol steps have been completed before allowing file operations. This is a generic tool - protocol steps and checklist items are defined in your .protocol-enforcer.json configuration file. Supports hook-specific filtering.',
    inputSchema: {
      type: 'object',
      properties: {
        hook: {
          type: 'string',
          enum: ['user_prompt_submit', 'session_start', 'pre_tool_use', 'post_tool_use', 'stop'],
          description: 'REQUIRED: Which hook is calling this verification (e.g., "pre_tool_use", "user_prompt_submit"). Filters rules to only those applicable to this hook.'
        },
        tool_name: {
          type: 'string',
          description: 'Optional: name of the tool being called (e.g., "Write", "Edit"). Used for tool-specific filtering when combined with hook. Only applies when hook is "pre_tool_use" or "post_tool_use".'
        },
        protocol_steps_completed: {
          type: 'array',
          items: { type: 'string' },
          description: 'List of protocol step names that have been completed (e.g., ["planning", "analysis"]). Step names must match those defined in your .protocol-enforcer.json config.'
        },
        checklist_items_checked: {
          type: 'array',
          items: { type: 'string' },
          description: 'List of checklist items that were verified. Items should match those defined in your .protocol-enforcer.json config.'
        }
      },
      required: ['hook', 'protocol_steps_completed', 'checklist_items_checked']
    }
  },
  {
    name: 'get_compliance_status',
    description: 'Get current compliance check statistics and recent violations',
    inputSchema: {
      type: 'object',
      properties: {}
    }
  },
  {
    name: 'get_protocol_config',
    description: 'Get the current protocol enforcer configuration',
    inputSchema: {
      type: 'object',
      properties: {}
    }
  },
  {
    name: 'authorize_file_operation',
    description: 'MANDATORY before ANY file write/edit operation. Validates the operation token from verify_protocol_compliance. Optionally creates 60-minute session token for multi-tool workflows.',
    inputSchema: {
      type: 'object',
      properties: {
        operation_token: {
          type: 'string',
          description: 'The operation token received from verify_protocol_compliance. Required for authorization.'
        },
        session_id: {
          type: 'string',
          description: 'Optional: Claude Code session ID. If provided, creates a 60-minute session token that allows subsequent tools without repeated protocol flows. Reduces overhead from ~16 calls to ~4 calls per multi-tool workflow.'
        }
      },
      required: []
    }
  }
 ];

 // Main MCP message handler
 async function handleMessage(message) {
  const { method, params, id } = message;

  // BUG FIX v2.0.14: Handle notifications (no id field) separately from requests
  // Notifications should NEVER receive a response (neither success nor error)
  // This fixes the "Received a response for an unknown message ID" error
  const isNotification = (id === undefined || id === null);

  // Handle notifications silently without sending any response
  if (isNotification) {
    if (method === 'notifications/initialized') {
      // Client has finished initializing - handle silently
      console.error('[protocol-enforcer] Client initialized');
      return null; // No response for notifications
    }
    // For other unknown notifications, log but don't respond
    console.error(`[protocol-enforcer] Received notification: ${method}`);
    return null; // No response for notifications
  }

  // For requests (messages with an id), use the actual ID
  const requestId = id;

  switch (method) {
    case 'initialize':
      return {
        jsonrpc: '2.0',
        id: requestId,
        result: {
          protocolVersion: '2024-11-05',
          serverInfo: {
            name: 'protocol-enforcer',
            version: '3.0.1'
          },
          capabilities: {
            tools: {}
          }
        }
      };

    case 'tools/list':
      return {
        jsonrpc: '2.0',
        id: requestId,
        result: { tools }
      };

    case 'tools/call':
      const { name, arguments: args } = params;
      let result;
      switch (name) {
        case 'initialize_protocol_config':
          result = await initializeProtocolConfig(args || {});
          break;
        case 'verify_protocol_compliance':
          result = await verifyProtocolCompliance(args || {});
          break;
        case 'get_compliance_status':
          result = await getComplianceStatus();
          break;
        case 'get_protocol_config':
          result = await getProtocolConfig();
          break;
        case 'authorize_file_operation':
          result = await authorizeFileOperation(args || {});
          break;
        default:
          result = {
            content: [{
              type: 'text',
              text: JSON.stringify({ error: `Unknown tool: ${name}` })
            }],
            isError: true
          };
      }
      return {
        jsonrpc: '2.0',
        id: requestId,
        result
      };

    default:
      return {
        jsonrpc: '2.0',
        id: requestId,
        error: {
          code: -32601,
          message: `Method not found: ${method}`
        }
      };
  }
 }

 // Send JSON-RPC error response
 function sendError(id, code, message, data) {
  const response = {
    jsonrpc: '2.0',
    id: id,
    error: {
      code: code,
      message: message,
      data: data
    }
  };
  console.error(`[protocol-enforcer] Sending error for id=${id}, code=${code}, message=${message}`);
  console.log(JSON.stringify(response));
 }

 // Stdio transport
 async function main() {
  loadConfig();

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    terminal: false
  });

  rl.on('line', async (line) => {
    try {
      // Debug logging: Log incoming JSON for parse error investigation
      if (process.env.DEBUG_MCP) {
        console.error('[protocol-enforcer] Received line:', line.slice(0, 200) + (line.length > 200 ? '...' : ''));
      }
      const message = JSON.parse(line);
      const response = await handleMessage(message);
      // BUG FIX v2.0.14: Only send response if not null (notifications return null)
      if (response !== null) {
        console.log(JSON.stringify(response));
      }
    } catch (error) {
      // Try to extract ID from message, otherwise use -1
      let requestId = -1;
      try {
        const partialParse = JSON.parse(line);
        if (partialParse && partialParse.id !== undefined) {
          requestId = partialParse.id;
        }
      } catch (e) {
        // If we can't even partially parse, use -1
      }

      console.error('[protocol-enforcer] Error:', error.message);
      console.error('[protocol-enforcer] Line:', line.slice(0, 500));

      // Distinguish parameter validation errors (-32602) from other errors
      if (error instanceof ValidationError) {
        sendError(requestId, -32602, 'Invalid params', error.message);
      } else if (error.name === 'SyntaxError') {
        sendError(requestId, -32700, 'Parse error', error.message);
      } else {
        sendError(requestId, -32603, 'Internal error', error.message);
      }
    }
  });

  // Graceful shutdown when STDIN closes (client disconnects)
  rl.on('close', () => {
    console.error('[protocol-enforcer] STDIN closed, shutting down gracefully');
    process.exit(0);
  });

  // Handle termination signals
  process.on('SIGTERM', () => {
    console.error('[protocol-enforcer] Received SIGTERM, shutting down');
    process.exit(0);
  });

  process.on('SIGINT', () => {
    console.error('[protocol-enforcer] Received SIGINT, shutting down');
    process.exit(0);
  });
 }

 main().catch(console.error);

diff --git a/LOOP_PROMPT.md b/LOOP_PROMPT.md
diff --git a/package.json b/package.json
 {
  "name": "protocol-enforcer-mcp",
  "version": "3.0.1",
  "description": "MCP server that enforces mandatory supervisor protocol compliance before allowing file operations",
  "author": "Jason Lusk <[email protected]>",
  "license": "MIT",
  "main": "index.js",
  "bin": {
    "protocol-enforcer": "./index.js"
  },
  "engines": {
    "node": ">=14.0.0"
  },
  "keywords": [
    "mcp",
    "model-context-protocol",
    "protocol-enforcer",
    "ai-assistant",
    "code-quality",
    "compliance"
  ]
 }
diff --git a/post-tool-use-verify.cjs b/post-tool-use-verify.cjs
 #!/usr/bin/env node
 /**
 * PostToolUse Hook - Automated verification and code quality checks
 * Runs after Write/Edit operations to ensure code quality standards
 */

 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');

 let input = '';
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
  try {
    const hookData = JSON.parse(input);
    const { tool, parameters } = hookData;

    // Extract file path from tool parameters
    let filePath = null;
    if (parameters && parameters.file_path) {
      filePath = parameters.file_path;
    }

    const checks = [];

    // ┌─────────────────────────────────────────────────────────┐
    // │ CHECK 1: GraphQL operations modified - run codegen      │
    // └─────────────────────────────────────────────────────────┘
    if (filePath && filePath.includes('src/graphql/operations/')) {
      checks.push('GraphQL operations modified - running codegen');
      try {
        execSync('yarn graphql:codegen', {
          cwd: '/Users/jasonlusk/src/ph/smartpass-admin-ui',
          stdio: 'pipe',
          timeout: 30000
        });
        checks.push('✅ GraphQL codegen completed successfully');
      } catch (e) {
        checks.push(`⚠️  GraphQL codegen failed: ${e.message}`);
        process.stderr.write(`\n⚠️  PostToolUse: GraphQL codegen failed\n${e.message}\n`);
      }
    }

    // ┌─────────────────────────────────────────────────────────┐
    // │ CHECK 2: Run linting for TypeScript/SCSS files          │
    // └─────────────────────────────────────────────────────────┘
    if (filePath && (filePath.endsWith('.ts') || filePath.endsWith('.tsx') || filePath.endsWith('.scss'))) {
      checks.push('Running code quality checks');
      try {
        execSync('yarn lint:all', {
          cwd: '/Users/jasonlusk/src/ph/smartpass-admin-ui',
          stdio: 'pipe',
          timeout: 60000
        });
        checks.push('✅ All linting checks passed');
      } catch (e) {
        // Lint failures should not block, but should be reported
        checks.push(`⚠️  Linting found issues - please fix before committing`);
        process.stderr.write(`\n⚠️  PostToolUse: Linting found issues\n${e.stdout ? e.stdout.toString() : e.message}\n`);
      }
    }

    // ┌─────────────────────────────────────────────────────────┐
    // │ CHECK 3: Verify no console.log statements               │
    // └─────────────────────────────────────────────────────────┘
    if (filePath && (filePath.endsWith('.ts') || filePath.endsWith('.tsx'))) {
      try {
        const content = fs.readFileSync(filePath, 'utf8');
        const consoleLogMatches = content.match(/console\.log\(/g);
        if (consoleLogMatches && consoleLogMatches.length > 0) {
          checks.push(`⚠️  Found ${consoleLogMatches.length} console.log() statement(s) - remove before committing`);
        } else {
          checks.push('✅ No console.log statements found');
        }
      } catch (e) {
        // File read error - skip check
      }
    }

    // Output results
    if (checks.length > 0) {
      const response = {
        hookSpecificOutput: {
          hookEventName: "PostToolUse",
          verificationResults: checks
        }
      };
      console.log(JSON.stringify(response));
      process.stderr.write('\n📋 PostToolUse verification:\n' + checks.map(c => '  ' + c).join('\n') + '\n');
    }

    process.exit(0);
  } catch (e) {
    // Don't block on hook errors
    process.stderr.write(`\n⚠️  PostToolUse hook error: ${e.message}\n`);
    process.exit(0);
  }
 });
diff --git a/post-tool-use.cjs b/post-tool-use.cjs
 #!/usr/bin/env node

 /**
 * post-tool-use.cjs - TEACH Gate Tracking + Immediate Reminders
 *
 * Forces agents to record experiences after completing work.
 * Marks sessions for recording - sessions cannot be reused until record_experience called.
 * FIXED: 24-hour TTL on recording tokens (prevents accumulation)
 * FIXED: Immediate reminders after Write/Edit
 *
 * Hook Type: TEACH gate tracking - non-blocking
 * Trigger: After tool execution
 * Purpose: Mark sessions for recording requirement
 */

 const fs = require('fs');
 const path = require('path');
 const os = require('os');

 // Tools that should trigger recording requirement
 const RECORDING_TRIGGERS = [
  'Write',
  'Edit',
  'NotebookEdit'
 ];

 /**
 * Get consistent session ID across all hooks
 */
 function getSessionId() {
  if (process.env.CLAUDE_SESSION_ID) {
    return process.env.CLAUDE_SESSION_ID;
  }

  const sessionFilePath = path.join(os.homedir(), '.protocol-current-session-id');
  try {
    if (fs.existsSync(sessionFilePath)) {
      const sessionData = JSON.parse(fs.readFileSync(sessionFilePath, 'utf8'));
      const age = Date.now() - sessionData.created;
      if (age < 8 * 60 * 60 * 1000) {
        return sessionData.session_id;
      }
    }
  } catch (err) {
    console.error(`[session-id] Failed to read session file: ${err.message}`);
  }

  return 'default-session';
 }

 async function handler(args) {
  try {
    const { toolName, success } = args;

    // Only trigger recording for relevant tools
    if (!RECORDING_TRIGGERS.includes(toolName)) {
      return { shouldBlock: false };
    }

    // Get the active session ID
    const sessionId = getSessionId();

    if (!sessionId) {
      console.error('[post-tool-use] No session ID found - skipping TEACH gate');
      return { shouldBlock: false };
    }

    // Create recording requirement token for this session
    // FIXED: Added 24-hour TTL to prevent infinite accumulation
    const tokenPath = path.join(os.homedir(), `.protocol-recording-required-${sessionId}`);
    const tokenData = {
      created: new Date().toISOString(),
      expires: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(), // 24-hour TTL
      sessionId,
      toolName,
      success: success !== false,
      requirement: 'TEACH - record_experience must be called before session reuse'
    };

    try {
      fs.writeFileSync(tokenPath, JSON.stringify(tokenData, null, 2));
      console.error(`⚠️ TEACH phase required - call record_experience`);
    } catch (err) {
      console.error(`[post-tool-use] Failed to create recording token: ${err.message}`);
      console.error(`[post-tool-use] This is not critical - continuing`);
    }

    // This hook doesn't block the current operation
    // It marks the session for recording requirement
    // Future attempts to use Write/Edit will be blocked until record_experience called
    return { shouldBlock: false };

  } catch (error) {
    console.error('[post-tool-use] Error:', error.message);
    // Never block on error in post-tool-use
    return { shouldBlock: false };
  }
 }

 // Export for Claude Code hooks
 module.exports = handler;

 // CLI execution support
 if (require.main === module) {
  const args = {
    toolName: process.argv[2] || 'Write',
    success: process.argv[3] !== 'false'
  };

  handler(args).then(result => {
    console.log(JSON.stringify(result, null, 2));
  }).catch(err => {
    console.error('Error:', err);
    process.exit(1);
  });
 }
diff --git a/pre-compact-handoff.cjs b/pre-compact-handoff.cjs
 #!/usr/bin/env node

 /**
 * pre-compact-handoff.cjs - Last Chance Reminder
 *
 * Reminds to record experiences before context compaction
 * Checks for incomplete recording tokens
 * Clear warning that compaction will lose session memory
 * Gives agent last chance to complete TEACH phase
 *
 * Hook Type: Non-blocking reminder
 * Trigger: Before context compaction
 */

 let input = '';
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
  try {
    const hookData = JSON.parse(input);
    const fs = require('fs');
    const path = require('path');
    const os = require('os');

    const sessionId = hookData.sessionId || 'unknown';
    const trigger = hookData.trigger || 'unknown'; // 'auto' or 'manual'

    // Check for incomplete recording tokens
    const homeDir = os.homedir();
    const files = fs.readdirSync(homeDir);
    const recordingTokens = files.filter(f => f.startsWith('.protocol-recording-required-'));

    // Log compaction event (concise)
    if (recordingTokens.length > 0) {
      console.error(`⚠️ Compaction triggered. ${recordingTokens.length} unrecorded session(s).`);
      console.error(`   Call record_experience now to preserve learnings.`);
    } else {
      console.error(`✅ Compaction triggered - all sessions recorded`);
    }

    process.exit(0);
  } catch (e) {
    console.error(`\n⚠️  PreCompact hook error: ${e.message}`);
    process.exit(0); // Don't block compaction on error
  }
 });
diff --git a/pre-tool-use.cjs b/pre-tool-use.cjs
 #!/usr/bin/env node

 /**
 * pre-tool-use.cjs - Three-Gate Enforcement (TEACH → LEARN → REASON)
 *
 * Blocks Write/Edit/NotebookEdit until THREE gates cleared:
 * 1. TEACH gate: Previous session(s) must be recorded
 * 2. LEARN gate: Must search past experiences
 * 3. REASON gate: Must complete reasoning cycle
 *
 * Hook Type: Blocking
 * Trigger: Before tool execution
 */

 const fs = require('fs');
 const path = require('path');
 const os = require('os');

 // Tools that require full cycle (all three gates)
 const PROTECTED_TOOLS = [
  'Write',
  'Edit',
  'NotebookEdit',
  'WebSearch'
 ];

 // Tools that are ALWAYS exempt (no authorization needed)
 const EXEMPT_TOOLS = [
  'Read',
  'Glob',
  'Grep',
  'Bash',
  'mcp__memory_augmented_reasoning__search_experiences',
  'mcp__memory_augmented_reasoning__record_experience',
  'mcp__memory_augmented_reasoning__informed_reasoning',
  'mcp__memory_augmented_reasoning__query_reasoning_memory',
  'mcp__memory_augmented_reasoning__export_experiences',
  'mcp__memory_augmented_reasoning__create_memory_library',
  'mcp__memory_augmented_reasoning__list_memory_libraries',
  'mcp__memory_augmented_reasoning__switch_memory_library',
  'mcp__memory_augmented_reasoning__get_current_library_info',
  'mcp__memory_augmented_reasoning__create_system_json',
  'mcp__memory_augmented_reasoning__get_system_json',
  'mcp__memory_augmented_reasoning__search_system_json',
  'mcp__memory_augmented_reasoning__list_system_json',
  'mcp__protocol_enforcer__verify_protocol_compliance',
  'mcp__protocol_enforcer__authorize_file_operation',
  'mcp__protocol_enforcer__get_protocol_config',
  'mcp__protocol_enforcer__get_compliance_status',
  'mcp__protocol_enforcer__initialize_protocol_config',
  'mcp__protocol_enforcer__check_protocol_compliance',
  'mcp__advanced_reasoning__advanced_reasoning',
  'mcp__advanced_reasoning__query_reasoning_memory',
  'mcp__advanced_reasoning__create_memory_library',
  'mcp__advanced_reasoning__list_memory_libraries',
  'mcp__advanced_reasoning__switch_memory_library',
  'mcp__advanced_reasoning__get_current_library_info',
  'mcp__advanced_reasoning__create_system_json',
  'mcp__advanced_reasoning__get_system_json',
  'mcp__advanced_reasoning__search_system_json',
  'mcp__advanced_reasoning__list_system_json',
  // Task tools are ALWAYS exempt to prevent deadlock
  'Task',
  'TaskCreate',
  'TaskUpdate',
  'TaskGet',
  'TaskList',
  'TaskOutput',
  'TaskStop'
 ];

 /**
 * Get consistent session ID across all hooks
 * Priority chain: CLAUDE_SESSION_ID env → persistent session file → generate new
 */
 function getSessionId() {
  if (process.env.CLAUDE_SESSION_ID) {
    return process.env.CLAUDE_SESSION_ID;
  }

  const sessionFilePath = path.join(os.homedir(), '.protocol-current-session-id');
  try {
    if (fs.existsSync(sessionFilePath)) {
      const sessionData = JSON.parse(fs.readFileSync(sessionFilePath, 'utf8'));
      const age = Date.now() - sessionData.created;
      if (age < 8 * 60 * 60 * 1000) {
        return sessionData.session_id;
      }
    }
  } catch (err) {
    console.error(`[session-id] Failed to read session file: ${err.message}`);
  }

  // If no valid session, return default - will use this for token checks
  return 'default-session';
 }

 /**
 * Cleanup helper with logging
 */
 function cleanupToken(tokenPath, reason) {
  try {
    if (fs.existsSync(tokenPath)) {
      fs.unlinkSync(tokenPath);
      console.error(`[pre-tool-use] ✓ Cleaned up token: ${path.basename(tokenPath)} (${reason})`);
      return true;
    }
    return false;
  } catch (err) {
    console.error(`[pre-tool-use] ✗ Failed to cleanup ${path.basename(tokenPath)}: ${err.message}`);
    console.error(`[pre-tool-use]   Token path: ${tokenPath}`);
    console.error(`[pre-tool-use]   Error code: ${err.code}`);
    return false;
  }
 }

 /**
 * TEACH GATE: Check if previous sessions have unrecorded work
 * Blocks if ANY .protocol-recording-required-* tokens exist
 */
 function checkTEACHGate() {
  try {
    const homeDir = os.homedir();
    const files = fs.readdirSync(homeDir);
    const recordingTokens = files.filter(f => f.startsWith('.protocol-recording-required-'));

    if (recordingTokens.length === 0) {
      return { passed: true };
    }

    // Check each token for expiry (>24 hours old)
    const now = Date.now();
    const maxAge = 24 * 60 * 60 * 1000; // 24 hours
    const validTokens = [];

    recordingTokens.forEach(tokenFile => {
      try {
        const tokenPath = path.join(homeDir, tokenFile);
        const stats = fs.statSync(tokenPath);
        const ageMs = now - stats.mtimeMs;

        if (ageMs > maxAge) {
          // Clean up expired token
          cleanupToken(tokenPath, `expired (${Math.round(ageMs / 1000 / 60 / 60)}h old)`);
          return; // Skip this token
        }

        // FIX #6: Tampering detection for recording tokens
        try {
          const tokenContent = fs.readFileSync(tokenPath, 'utf8');
          const tokenData = JSON.parse(tokenContent);

          // Check file modification time vs token creation time
          const fileModifiedMs = stats.mtimeMs;
          const tokenCreatedMs = tokenData.created || tokenData.timestamp || 0;

          if (tokenCreatedMs > 0) {
            const fileAge = now - fileModifiedMs;
            const tokenAge = now - tokenCreatedMs;
            const ageDifference = Math.abs(fileAge - tokenAge);

            // Allow 5 second tolerance
            if (ageDifference > 5000) {
              console.error('[pre-tool-use] ⚠️  Recording token file modification detected');
              console.error(`[pre-tool-use]   File: ${tokenFile}`);
              console.error(`[pre-tool-use]   File age: ${Math.round(fileAge/1000)}s, Token age: ${Math.round(tokenAge/1000)}s`);
              console.error('[pre-tool-use]   WARNING: Manual editing bypasses TEACH gate validation');
            }
          }

          // Validate recording token structure
          if (!tokenData.sessionId && !tokenData.session_id) {
            console.error('[pre-tool-use] ⚠️  Recording token missing session ID - invalid structure');
            console.error(`[pre-tool-use]   File: ${tokenFile}`);
            console.error('[pre-tool-use]   Cleaning up invalid token');
            cleanupToken(tokenPath, 'invalid structure');
            return; // Skip this token
          }

          // Token is valid
          validTokens.push(tokenFile);

        } catch (parseErr) {
          // If token file is corrupted or invalid JSON
          console.error(`[pre-tool-use] ⚠️  Recording token is corrupted or invalid: ${tokenFile}`);
          console.error(`[pre-tool-use]   Error: ${parseErr.message}`);
          console.error('[pre-tool-use]   Cleaning up corrupted token');
          cleanupToken(tokenPath, 'corrupted file');
        }

      } catch (err) {
        console.error(`[pre-tool-use] Error checking token ${tokenFile}: ${err.message}`);
      }
    });

    if (validTokens.length === 0) {
      return { passed: true };
    }

    // BLOCK - unrecorded work exists
    return {
      passed: false,
      message: `⛔ TEACH Gate: ${validTokens.length} session(s) need record_experience first.
 Call record_experience({type: "effective|ineffective", domain, situation, approach, outcome, reasoning})
 Then: search_experiences → informed_reasoning → Write/Edit
 Tokens: ${validTokens.join(', ')}`
    };

  } catch (error) {
    console.error('[pre-tool-use] TEACH gate check error:', error.message);
    return { passed: true }; // Fail open on error
  }
 }

 /**
 * LEARN GATE: Check if search_experiences was called
 */
 function checkLEARNGate() {
  try {
    const sessionId = getSessionId();
    const searchTokenPath = path.join(os.homedir(), `.protocol-search-completed-${sessionId}`);

    if (!fs.existsSync(searchTokenPath)) {
      return {
        passed: false,
        message: `⛔ LEARN Gate: No search performed yet.
 Call search_experiences({query: "task keywords", limit: 10}) first.
 Then: informed_reasoning (4 phases) → Write/Edit authorized.`
      };
    }

    const tokenContent = fs.readFileSync(searchTokenPath, 'utf8');
    const tokenData = JSON.parse(tokenContent);

    // FIX #6: Tampering detection for search tokens
    try {
      const fileStats = fs.statSync(searchTokenPath);
      const fileModifiedMs = fileStats.mtimeMs;
      const tokenCreatedMs = tokenData.created_at || tokenData.timestamp || 0;

      if (tokenCreatedMs > 0) {
        const fileAge = Date.now() - fileModifiedMs;
        const tokenAge = Date.now() - tokenCreatedMs;
        const ageDifference = Math.abs(fileAge - tokenAge);

        // Allow 5 second tolerance for filesystem delays
        if (ageDifference > 5000) {
          console.error('[pre-tool-use] ⚠️  Search token file modification detected outside MCP server');
          console.error(`[pre-tool-use]   File: ${path.basename(searchTokenPath)}`);
          console.error(`[pre-tool-use]   File age: ${Math.round(fileAge/1000)}s, Token age: ${Math.round(tokenAge/1000)}s`);
          console.error('[pre-tool-use]   WARNING: Manual editing bypasses LEARN gate validation');
          console.error('[pre-tool-use]   TIP: Call search_experiences to create legitimate tokens');
        }
      }

      // Validate search token structure
      if (!tokenData.sessionId && !tokenData.session_id) {
        console.error('[pre-tool-use] ⚠️  Search token missing session ID - invalid structure');
        cleanupToken(searchTokenPath, 'invalid structure');
        return {
          passed: false,
          message: `⛔ LEARN Gate: Invalid search token (malformed/tampered).
 Call search_experiences({query: "task keywords", limit: 10}) to create valid token.`
        };
      }
    } catch (err) {
      console.error(`[pre-tool-use] Warning: Could not validate search token integrity: ${err.message}`);
      // Continue - don't block on validation errors
    }

    const expires = new Date(tokenData.expires);
    const now = new Date();

    if (expires <= now) {
      cleanupToken(searchTokenPath, 'expired');
      return {
        passed: false,
        message: `⛔ LEARN Gate: Search token expired (5-min TTL).
 Call search_experiences({query: "task keywords", limit: 10}) again.
 Each request needs fresh search → informed_reasoning → Write/Edit.`
      };
    }

    return { passed: true };

  } catch (error) {
    console.error('[pre-tool-use] LEARN gate check error:', error.message);
    return {
      passed: false,
      message: `⛔ LEARN Gate: Error validating search token.
 Call search_experiences({query: "task keywords", limit: 10}) to create fresh token.
 Error: ${error.message}

 This will create a new search token and resolve the error.

 If error persists, check file permissions in home directory.`
    };
  }
 }

 /**
 * REASON GATE: Check if informed_reasoning created session token
 */
 function checkREASONGate() {
  try {
    const sessionId = getSessionId();
    const homeDir = os.homedir();
    const files = fs.readdirSync(homeDir);

    // Look for session token for current session
    const sessionTokenPattern = new RegExp(`\\.protocol-session-${sessionId}.*\\.json$`);
    const sessionFiles = files.filter(f => sessionTokenPattern.test(f));

    for (const file of sessionFiles) {
      const tokenPath = path.join(homeDir, file);
      try {
        const tokenContent = fs.readFileSync(tokenPath, 'utf8');
        const tokenData = JSON.parse(tokenContent);

        // FIX #6: Tampering detection - Check file integrity
        const fileStats = fs.statSync(tokenPath);
        const fileModifiedMs = fileStats.mtimeMs;
        const tokenCreatedMs = tokenData.created_at || tokenData.timestamp || 0;

        // If file modified significantly after token creation, it may be tampered
        if (tokenCreatedMs > 0) {
          const fileAge = Date.now() - fileModifiedMs;
          const tokenAge = Date.now() - tokenCreatedMs;
          const ageDifference = Math.abs(fileAge - tokenAge);

          // Allow 5 second tolerance for filesystem delays
          if (ageDifference > 5000) {
            console.error('[pre-tool-use] ⚠️  Session file modification detected outside MCP server');
            console.error(`[pre-tool-use]   File: ${file}`);
            console.error(`[pre-tool-use]   File age: ${Math.round(fileAge/1000)}s, Token age: ${Math.round(tokenAge/1000)}s`);
            console.error(`[pre-tool-use]   Difference: ${Math.round(ageDifference/1000)}s`);
            console.error('[pre-tool-use]   WARNING: Manual editing of session files can bypass validation');
            console.error('[pre-tool-use]   TIP: Use informed_reasoning to create legitimate session tokens');
            // Continue - warn but don't block (could be legitimate clock skew)
          }
        }

        // FIX #6: Validate session structure
        if (tokenData.session_id || tokenData.sessionId) {
          // Has session ID - validate structure
          if (tokenData.phases && typeof tokenData.phases === 'object') {
            // Check if claiming all phases complete but artifacts not verified
            if (tokenData.allPhasesComplete === true && tokenData.artifactsVerified === false) {
              console.error('[pre-tool-use] ⚠️  Session claims completion but artifacts not verified');
              console.error('[pre-tool-use]   File: ${file}');
              console.error('[pre-tool-use]   This indicates potential tampering or incomplete validation');
              console.error('[pre-tool-use]   Rejecting session token - complete informed_reasoning properly');
              cleanupToken(tokenPath, 'invalid artifacts verification');
              continue; // Skip this token, try next one
            }

            // Validate phase completion markers exist
            const hasAnalyze = tokenData.phases.analyze && tokenData.phases.analyze.completed;
            const hasIntegrate = tokenData.phases.integrate && tokenData.phases.integrate.completed;
            const hasReason = tokenData.phases.reason && tokenData.phases.reason.completed;

            if (!hasAnalyze || !hasIntegrate || !hasReason) {
              console.error('[pre-tool-use] ⚠️  Session token missing required phase completions');
              console.error(`[pre-tool-use]   File: ${file}`);
              console.error(`[pre-tool-use]   Analyze: ${hasAnalyze}, Integrate: ${hasIntegrate}, Reason: ${hasReason}`);
              console.error('[pre-tool-use]   This indicates incomplete reasoning cycle or tampering');
              console.error('[pre-tool-use]   Rejecting session token - complete all 4 phases');
              cleanupToken(tokenPath, 'incomplete phase markers');
              continue; // Skip this token
            }
          }
        }

        // Check expiry (60-minute TTL)
        const expiresAt = tokenData.expires_at || tokenData.expires;
        if (expiresAt > Date.now()) {
          // Valid session token found - passed all integrity checks
          console.error(`[pre-tool-use] ✓ Session token validated: ${file}`);
          return { passed: true };
        } else {
          // Expired - clean up
          cleanupToken(tokenPath, 'expired');
        }
      } catch (err) {
        console.error(`[pre-tool-use] Error reading session token ${file}: ${err.message}`);
      }
    }

    // No valid session token
    return {
      passed: false,
      message: `⛔ REASON Gate: No session token found.
 Complete informed_reasoning (analyze → integrate → reason → record phases).
 This creates 60-min session token authorizing Write/Edit.`
    };

  } catch (error) {
    console.error('[pre-tool-use] REASON gate check error:', error.message);
    return {
      passed: false,
      message: `⛔ REASON Gate: Error validating session token.
 Complete informed_reasoning (4 phases) to create fresh token.
 Error: ${error.message}`
    };
  }
 }

 async function handler(args) {
  try {
    const { toolName } = args;

    console.error(`[pre-tool-use] Checking tool: ${toolName}`);

    // Check if tool is exempt (always allow)
    if (EXEMPT_TOOLS.includes(toolName)) {
      console.error(`[pre-tool-use] Tool ${toolName} is exempt - allowing`);
      return { shouldBlock: false };
    }

    // Check if tool is protected (requires authorization)
    if (!PROTECTED_TOOLS.includes(toolName)) {
      console.error(`[pre-tool-use] Tool ${toolName} not in protected list - allowing`);
      return { shouldBlock: false };
    }

    // Protected tool - enforce THREE gates: TEACH → LEARN → REASON
    console.error(`[pre-tool-use] Protected tool ${toolName} - checking three gates`);

    // GATE 1: TEACH (previous work must be recorded)
    const teachGate = checkTEACHGate();
    if (!teachGate.passed) {
      console.error(`[pre-tool-use] TEACH gate blocking ${toolName}`);
      return {
        shouldBlock: true,
        message: teachGate.message
      };
    }

    // GATE 2: LEARN (must search past experiences)
    const learnGate = checkLEARNGate();
    if (!learnGate.passed) {
      console.error(`[pre-tool-use] LEARN gate blocking ${toolName}`);
      return {
        shouldBlock: true,
        message: learnGate.message
      };
    }

    // GATE 3: REASON (must complete reasoning cycle)
    const reasonGate = checkREASONGate();
    if (!reasonGate.passed) {
      console.error(`[pre-tool-use] REASON gate blocking ${toolName}`);
      return {
        shouldBlock: true,
        message: reasonGate.message
      };
    }

    // All three gates passed - allow operation
    console.error(`[pre-tool-use] All three gates passed - allowing ${toolName}`);

    // Invalidate session token AFTER Write/Edit to force fresh LEARN per task
    if (toolName === 'Write' || toolName === 'Edit' || toolName === 'NotebookEdit') {
      const homeDir = os.homedir();
      const files = fs.readdirSync(homeDir);
      const sessionTokens = files.filter(f => f.match(/\.protocol-session-.*\.json$/));

      sessionTokens.forEach(tokenFile => {
        const tokenPath = path.join(homeDir, tokenFile);
        cleanupToken(tokenPath, 'Session invalidated after file modification');
      });
    }

    return { shouldBlock: false };

  } catch (error) {
    console.error('[pre-tool-use] Error:', error.message);
    console.error('[pre-tool-use] Stack:', error.stack);
    // On error, block to fail-safe
    return {
      shouldBlock: true,
      message: `⛔ Protocol enforcement error: ${error.message}\n\nBlocking operation for safety.`
    };
  }
 }

 // Export for Claude Code hooks
 module.exports = handler;

 // CLI execution support
 if (require.main === module) {
  const args = {
    toolName: process.argv[2] || 'Write'
  };

  handler(args).then(result => {
    console.log(JSON.stringify(result, null, 2));
    process.exit(result.shouldBlock ? 1 : 0);
  }).catch(err => {
    console.error('Error:', err);
    process.exit(1);
  });
 }
diff --git a/record-tool-execution.cjs b/record-tool-execution.cjs
 #!/usr/bin/env node
 /**
 * PostToolUse Hook - Record Tool Execution for Protocol Verification
 * Records ALL tool calls to ~/.protocol-tool-log.json for cross-referencing
 * during protocol compliance checks
 */

 const fs = require('fs');
 const path = require('path');
 const os = require('os');

 let input = '';
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
  try {
    const hookData = JSON.parse(input);

    // Extract correct fields from hook JSON
    const { tool_name, tool_input, session_id } = hookData;

    // Tool log file path
    const toolLogPath = path.join(os.homedir(), '.protocol-tool-log.json');

    // Read existing log
    let log = [];
    try {
      if (fs.existsSync(toolLogPath)) {
        log = JSON.parse(fs.readFileSync(toolLogPath, 'utf8'));
      }
    } catch (err) {
      // Start fresh if log is corrupted
      log = [];
    }

    // Use session ID from hook data (consistent across all tool calls in session)
    const sessionId = session_id || `session_${Date.now()}`;

    // Record tool call
    log.push({
      sessionId,
      toolName: tool_name,
      parameters: tool_input || {},
      timestamp: new Date().toISOString()
    });

    // Keep only last 1000 entries to prevent unbounded growth
    if (log.length > 1000) {
      log = log.slice(-1000);
    }

    // Write updated log
    fs.writeFileSync(toolLogPath, JSON.stringify(log, null, 2), 'utf8');

    // Silent success - no output needed
    process.exit(0);
  } catch (e) {
    // Silent failure - don't block tool execution
    process.stderr.write(`[record-tool-execution] Warning: ${e.message}\n`);
    process.exit(0);
  }
 });
diff --git a/session-end-handoff.cjs b/session-end-handoff.cjs
 #!/usr/bin/env node
 /**
 * SessionEnd Hook - Triggers automatic experience extraction
 *
 * Spawns background process to extract experiences from session transcript
 * using LLM-based pattern detection.
 */

 const { spawn, execSync } = require('child_process');

 /**
 * Get Claude API key from macOS keychain or environment
 */
 function getApiKey() {
  // Try macOS keychain first (where Claude Code stores it)
  if (process.platform === 'darwin') {
    try {
      const key = execSync('security find-generic-password -s "Claude Code" -w', {
        encoding: 'utf8',
        stdio: ['pipe', 'pipe', 'ignore']
      }).trim();
      if (key) return key;
    } catch (error) {
      // Keychain read failed, try env vars
    }
  }

  // Fallback to environment variables
  return process.env.CLAUDE_API_KEY || process.env.ANTHROPIC_API_KEY || null;
 }

 let input = '';
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
  try {
    const hookData = JSON.parse(input);
    const sessionId = hookData.sessionId || 'unknown';
    const reason = hookData.reason || 'unknown';

    // Log session end event
    console.error(`\n📋 SessionEnd: Session ended`);
    console.error(`   Session ID: ${sessionId}`);
    console.error(`   Reason: ${reason}`);

    // Trigger automatic experience extraction (if enabled)
    if (sessionId !== 'unknown' && process.env.AUTO_EXTRACT_LEARNINGS !== 'false') {
      const apiKey = getApiKey();

      if (!apiKey) {
        console.error(`   ⚠️  No API key found (checked keychain and env vars)`);
        console.error(`   💡 Set CLAUDE_API_KEY or ANTHROPIC_API_KEY environment variable`);
      } else {
        console.error(`   🤖 Triggering automatic experience extraction...`);

        // Spawn detached background process
        const child = spawn('memory-augmented-reasoning', [
          'extract-experiences',
          '--session', sessionId,
          '--auto',
          '--notify'
        ], {
          detached: true,
          stdio: 'ignore',
          env: {
            ...process.env,
            CLAUDE_API_KEY: apiKey
          }
        });

        // Detach from parent process
        child.unref();

        console.error(`   📦 Extraction running in background (you'll be notified when complete)`);
      }
    } else if (process.env.AUTO_EXTRACT_LEARNINGS === 'false') {
      console.error(`   ⏸️  Auto-extraction disabled (AUTO_EXTRACT_LEARNINGS=false)`);
      console.error(`   💡 Run manually: memory-augmented-reasoning extract-experiences --session ${sessionId} --auto`);
    }

    process.exit(0);
  } catch (e) {
    console.error(`\n⚠️  SessionEnd hook error: ${e.message}`);
    process.exit(0); // Don't block session end on error
  }
 });
diff --git a/session-start-handoff.cjs b/session-start-handoff.cjs
 "#!/usr/bin/env node\n/**\n * SessionStart Hook - Logs session start events\n * Simplified version - handoff files removed\n *\n * Note: Context continuity is now handled by Claude Code's built-in\n * compaction and summarization. Experiences should be recorded manually\n * during the session using mcp__memory-augmented-reasoning__record_experience tool.\n */\n\nlet input = '';\nprocess.stdin.on('data', chunk => input += chunk);\nprocess.stdin.on('end', () => {\n  try {\n    // Parse hookData (contains sessionId, cwd, etc.)\n    JSON.parse(input);\n\n    // Log session start (concise)\n    console.error(`📋 Session started`);\n\n    // No context injection needed - Claude Code handles this\n    // Output empty (CORRECT format - plain text, not JSON with userPrompt)\n    console.log(\"\");\n\n    process.exit(0);\n  } catch (e) {\n    console.error(`\\n⚠️  SessionStart hook error: ${e.message}`);\n    console.log(\"\");\n    process.exit(0);\n  }\n});\n"
diff --git a/session-start.cjs b/session-start.cjs
 "#!/usr/bin/env node\n\n/**\n * session-start.cjs - Minimal Session Setup\n *\n * Does NOT inject prompts (moved to UserPromptSubmit to avoid spam)\n * Only logs session start for debugging\n *\n * Hook Type: Non-blocking setup\n * Trigger: When new session starts\n */\n\nlet input = '';\nprocess.stdin.on('data', chunk => input += chunk);\nprocess.stdin.on('end', () => {\n  try {\n    JSON.parse(input); // Parse hookData\n\n    // Just log, don't inject prompts\n    console.error('[session-start] New session started');\n    console.error('[session-start] Protocol enforcement active');\n\n    // No prompt injection - output empty (CORRECT format - plain text, not JSON)\n    console.log(\"\");\n\n    process.exit(0);\n  } catch (e) {\n    console.error(`[session-start] Error: ${e.message}`);\n    console.log(\"\");\n    process.exit(0);\n  }\n});\n"
diff --git a/stop.cjs b/stop.cjs
 "#!/usr/bin/env node\n\n/**\n * stop.cjs - TEACH Phase Reminder (with Loop Prevention)\n *\n * Reminds agent to complete TEACH phase\n * Runs when agent finishes responding\n * FIXED: Only reminds once per recording token to prevent infinite loop\n *\n * Hook Type: Non-blocking follow-up prompt\n * Trigger: After agent response\n */\n\nlet input = '';\nprocess.stdin.on('data', chunk => input += chunk);\nprocess.stdin.on('end', () => {\n  try {\n    const hookData = JSON.parse(input);\n\n    const fs = require('fs');\n    const path = require('path');\n    const os = require('os');\n\n    const homeDir = os.homedir();\n    const files = fs.readdirSync(homeDir);\n    const recordingTokens = files.filter(f => f.startsWith('.protocol-recording-required-'));\n\n    if (recordingTokens.length > 0) {\n      // Check if we've already reminded for these tokens\n      const reminderTrackPath = path.join(homeDir, '.protocol-stop-hook-reminders.json');\n      let remindedTokens = {};\n\n      try {\n        if (fs.existsSync(reminderTrackPath)) {\n          remindedTokens = JSON.parse(fs.readFileSync(reminderTrackPath, 'utf8'));\n        }\n      } catch (e) {\n        console.error(`[stop] Failed to read reminder tracking: ${e.message}`);\n        remindedTokens = {};\n      }\n\n      // Find tokens we haven't reminded about yet\n      const newTokens = recordingTokens.filter(token => !remindedTokens[token]);\n\n      if (newTokens.length > 0) {\n        // Mark these as reminded\n        newTokens.forEach(token => {\n          remindedTokens[token] = new Date().toISOString();\n        });\n\n        try {\n          fs.writeFileSync(reminderTrackPath, JSON.stringify(remindedTokens, null, 2));\n        } catch (e) {\n          console.error(`[stop] Failed to track reminders: ${e.message}`);\n        }\n\n        const reminderPrompt = `⚠️ Unrecorded work: Call record_experience before exit`;\n\n        // Output plain text (CORRECT format for Claude Code)\n        console.log(reminderPrompt);\n      } else {\n        // Already reminded - don't spam (output empty)\n        console.log(\"\");\n      }\n    } else {\n      console.log(\"\");\n    }\n\n    process.exit(0);\n  } catch (e) {\n    console.error(`[stop] Error: ${e.message}`);\n    console.log(\"\");\n    process.exit(0);\n  }\n});\n"
diff --git a/user-prompt-submit-reminder.cjs b/user-prompt-submit-reminder.cjs
 #!/usr/bin/env node
 /**
 * UserPromptSubmit Hook - Inject mandatory protocol reminder
 * Ensures Claude sees the informed_reasoning requirement before every response
 */

 const fs = require('fs');
 const path = require('path');

 let input = '';
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
  try {
    const hookData = JSON.parse(input);

    // Inject concise protocol reminder (Fix #14: 2-4 lines max, no ASCII art)
    const reminder = `🔵 NEW REQUEST - Protocol MANDATORY for ALL responses:
 1. search_experiences (LEARN gate) - ALWAYS FIRST
 2. informed_reasoning analyze phase (REASON gate)
 3. THEN respond to user

 ⛔ Do NOT respond to user until steps 1-2 complete.`;

    // Output injected prompt - CORRECT format for Claude Code
    // Option 1: Plain text (simpler and recommended)
    console.log(reminder);

    // Option 2: Structured JSON (alternative)
    // console.log(JSON.stringify({
    //   hookSpecificOutput: {
    //     hookEventName: "UserPromptSubmit",
    //     additionalContext: reminder
    //   }
    // }));

    process.exit(0);
  } catch (e) {
    console.error(`\n⚠️  UserPromptSubmit hook error: ${e.message}`);
    process.exit(0); // Don't block user prompt on error
  }
 });
diff --git a/user-prompt-submit.cjs b/user-prompt-submit.cjs
 #!/usr/bin/env node

 /**
 * user-prompt-submit.cjs - LEARN Gate State Tracking + Smart Reminders
 * Creates search requirement token AND injects reminder for task-like prompts
 * FIXED: Only reminds for tasks, not read-only questions
 * FIXED: Proactive token cleanup on every prompt
 */

 const fs = require('fs');
 const path = require('path');
 const os = require('os');

 /**
 * Proactive Token Cleanup
 * Removes all protocol tokens >24 hours old to prevent accumulation
 * Runs on every user prompt for maximum hygiene
 */
 function cleanupExpiredTokens() {
  const homeDir = os.homedir();
  const now = Date.now();
  const maxAge = 24 * 60 * 60 * 1000; // 24 hours

  let cleaned = 0;
  let errors = 0;

  try {
    const files = fs.readdirSync(homeDir);
    const protocolTokens = files.filter(f => f.startsWith('.protocol-'));

    protocolTokens.forEach(tokenFile => {
      try {
        const tokenPath = path.join(homeDir, tokenFile);
        const stats = fs.statSync(tokenPath);
        const ageMs = now - stats.mtimeMs;

        if (ageMs > maxAge) {
          fs.unlinkSync(tokenPath);
          cleaned++;
          console.error(`[cleanup] ✓ Removed expired token: ${tokenFile} (age: ${Math.round(ageMs / 1000 / 60 / 60)}h)`);
        }
      } catch (err) {
        errors++;
        console.error(`[cleanup] ✗ Failed to cleanup ${tokenFile}: ${err.message}`);
      }
    });

    if (cleaned > 0 || errors > 0) {
      console.error(`[cleanup] Cleanup complete: ${cleaned} removed, ${errors} errors`);
    }
  } catch (err) {
    console.error(`[cleanup] Directory scan failed: ${err.message}`);
  }
 }

 /**
 * Get consistent session ID across all hooks
 * Priority chain: CLAUDE_SESSION_ID env → persistent session file → generate new
 */
 function getSessionId() {
  // PRIORITY 1: Environment variable (set by Claude Code)
  if (process.env.CLAUDE_SESSION_ID) {
    return process.env.CLAUDE_SESSION_ID;
  }

  // PRIORITY 2: Persistent session file
  const sessionFilePath = path.join(os.homedir(), '.protocol-current-session-id');
  try {
    if (fs.existsSync(sessionFilePath)) {
      const sessionData = JSON.parse(fs.readFileSync(sessionFilePath, 'utf8'));
      // Check if session file is stale (>8 hours old)
      const age = Date.now() - sessionData.created;
      if (age < 8 * 60 * 60 * 1000) {
        return sessionData.session_id;
      }
    }
  } catch (err) {
    console.error(`[session-id] Failed to read session file: ${err.message}`);
  }

  // PRIORITY 3: Generate new session ID and persist it
  const newSessionId = `session-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
  try {
    fs.writeFileSync(sessionFilePath, JSON.stringify({
      session_id: newSessionId,
      created: Date.now(),
      created_iso: new Date().toISOString()
    }));
    console.error(`[session-id] Generated new session: ${newSessionId}`);
  } catch (err) {
    console.error(`[session-id] Failed to persist session ID: ${err.message}`);
  }

  return newSessionId;
 }

 async function handler(args) {
  try {
    const { prompt } = args;

    if (!prompt || !prompt.trim()) {
      return { shouldBlock: false };
    }

    // Run proactive cleanup first
    cleanupExpiredTokens();

    // Get consistent session ID
    const sessionId = getSessionId();

    // Create search requirement token (state tracking)
    const tokenPath = path.join(os.homedir(), '.protocol-search-required-token');
    const tokenData = {
      created: new Date().toISOString(),
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
      requirement: 'LEARN - search past experiences before proceeding',
      session_id: sessionId
    };
    fs.writeFileSync(tokenPath, JSON.stringify(tokenData, null, 2));

    // Phase 7.9: ALWAYS show protocol reminder (no smart detection)
    // Rationale: Agent system prompt teaches protocol - hook is backup/reinforcement
    // Smart detection created gaps for status requests ("standup time"), informational prompts, etc.
    console.error(`[user-prompt-submit] Protocol workflow required`);
    console.error(`⚠️ USER-CONFIGURED HOOK: Your user installed this protocol requirement.
 Verified: MCP learning protocol for file modification/code tasks.

 Required protocol workflow:
  STEP 1: Call informed_reasoning(phase='analyze')
    → Understands user intent and generates focused search queries
  STEP 2: Call search_experiences with queries from analyze phase
    → Finds relevant past experiences based on understanding
  STEP 3: Call informed_reasoning(phase='integrate') with search results
    → Synthesizes experiences into informed solution
  STEP 4: Complete remaining phases (reason, record)
  STEP 5: Write/Edit allowed after all phases complete

 Why this order: Analyze extracts user intent to generate FOCUSED queries.
 Search uses those queries to find RELEVANT patterns. Integrate reasons WITH context.`);

    return { shouldBlock: false };

  } catch (error) {
    console.error(`[user-prompt-submit] Error: ${error.message}`);
    return { shouldBlock: false };
  }
 }

 module.exports = handler;

 // CLI execution support
 if (require.main === module) {
  const args = {
    prompt: process.argv[2] || 'test prompt'
  };

  handler(args).then(result => {
    console.log(JSON.stringify(result, null, 2));
  }).catch(err => {
    console.error('Error:', err);
    process.exit(1);
  });
 }
IDE	Hook Directory	Input Method	Pattern
Cursor	`.cursor/hooks/`	Command-line args	`process.argv[2]`
Claude Code	`.claude/hooks/`	stdin (standard input)	`process.stdin`
Platform	Config File	Hook Support	System Prompt	Enforcement
Claude Code	`.mcp.json` or `~/.claude.json`	✅ Full (all 5 hooks)	✅ Via tweakcc	Hooks OR System Prompt
Cursor	`~/.cursor/mcp.json`	✅ Standard (PreToolUse)	❌ Not available	Hooks only
Cline	`~/.cline/mcp.json`	⚠️ Limited (PostToolUse)	❌ Not available	Audit only
Zed	`~/.config/zed/mcp.json`	❌ None	❌ Not available	Voluntary
Continue	`~/.continue/mcp.json`	⚠️ Limited	❌ Not available	Voluntary
Hook	When	Use Case
`user_prompt_submit`	Before processing user message	Pre-response checks, sequential thinking
`session_start`	At session initialization	Display requirements, initialize tracking
`pre_tool_use`	Before tool execution	Primary enforcement point for file operations
`post_tool_use`	After tool execution	Validation, linting, audit logging
`stop`	Before session termination	Compliance reporting, cleanup
Parameter	Type	Required	Description
`hook`	string	✅ Yes	Lifecycle point: `user_prompt_submit`, `session_start`, `pre_tool_use`, `post_tool_use`, `stop`
`tool_name`	string	No	Tool being called (`Write`, `Edit`) for tool-specific filtering
`protocol_steps_completed`	string[]	✅ Yes	Completed step names from config
`checklist_items_checked`	string[]	✅ Yes	Verified checklist items from config
Token File	Created By	Consumed By	Lifetime	Purpose
`.protocol-informed-reasoning-required`	user_prompt_submit hook	informed_reasoning (analyze)	2min	Signals requirement for informed_reasoning
`.protocol-informed-reasoning-token`	informed_reasoning (analyze)	PreToolUse hook	60s	Proves analysis completed
`.protocol-enforcer-token`	authorize_file_operation	PreToolUse hook	60s	Proves operation authorized
`.protocol-search-required-token`	informed_reasoning (when suggesting search)	search_experiences	5min	Enforces suggested searches
`.protocol-session-token`	informed_reasoning (with session_id)	user_prompt_submit hook	10min	Session optimization
Issue	Solution
Server not appearing	Check config file syntax, gist URL, file location, reload IDE
Configuration not loading	Verify `.protocol-enforcer.json` filename, check JSON syntax
Tools not working	Test with `get_protocol_config`, check tool names (must use full `mcp__protocol-enforcer__*`)
Token errors	Check `~/.protocol-enforcer-token` exists after `authorize_file_operation`
Method	Enforcement	Setup Complexity	Reliability	Debugging
Hooks	Hard block - cannot bypass	Medium (create scripts)	100% - External enforcement	Hard (check hook logs)
System Prompt	Soft requirement - Claude follows instructions	Low (install tweakcc)	95% - Depends on Claude	Easy (visible in prompt)
Both	Hard block + Instruction	High	Maximum	Medium
Issue	Solution
`tweakcc: command not found`	Install with `npm install -g tweakcc`
Claude doesn't follow protocol	Verify modifications applied: check `~/.tweakcc/system-prompts/` for your changes
Protocol ignored after update	Claude Code update reset prompts - re-run `npx tweakcc` and `npx tweakcc --apply`
Changes not taking effect	Full restart required (quit and relaunch), not just reload
Conflicts with other tweaks	Check `~/.tweakcc/system-prompts/` for multiple modifications to same file
Platform	Recommended Hooks	Strategy
Claude Code	All 5 hooks	Maximum enforcement
Cursor	PreToolUse + PostToolUse	Standard enforcement
Cline	PostToolUse only	Audit logging
Zed/Continue	None	Voluntary compliance
Feature	Claude Code	Cursor	Cline	Zed/Continue
Hooks Available	All 5	PreToolUse + PostToolUse	PostToolUse	None
Automatic Blocking	✅ Yes	✅ Yes	❌ No	❌ No
Recommended Steps	5-7 steps	3-5 steps	2-3 steps	1-2 steps
Enforcement Level	Maximum	Standard	Audit	Voluntary
Best For	Production	Development	Code review	Minimal