thanh-kit 2.5.0

package/templates/hooks/lib/ck-paths.cjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * ClaudeKit Paths - Centralized path constants for all temporary/runtime files
+ *
+ * All ClaudeKit temp files consolidated under /tmp/ck/ namespace for:
+ * - Cleaner /tmp directory (single namespace)
+ * - Easier cleanup (rm -rf /tmp/ck/)
+ * - Debugging (all state in one place)
+ * - No collisions with other tools
+ *
+ * Fixes:
+ * - #177: Race condition from shared global state file
+ * - #178: Scattered temp files consolidation
+ *
+ * @module ck-paths
+ */
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+// Root directory for all ClaudeKit temp files
+const CK_TMP_DIR = path.join(os.tmpdir(), 'ck');
+
+// Session-specific marker files (per-session, no race conditions)
+const MARKERS_DIR = path.join(CK_TMP_DIR, 'markers');
+
+// Global calibration data (shared by design - records compact thresholds)
+const CALIBRATION_PATH = path.join(CK_TMP_DIR, 'calibration.json');
+
+// Debug logs directory
+const DEBUG_DIR = path.join(CK_TMP_DIR, 'debug');
+
+/**
+ * Ensure directory exists
+ * @param {string} dirPath - Directory path to create
+ */
+function ensureDir(dirPath) {
+  try {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+  } catch (err) {
+    // Silent fail - non-critical, but log for debugging
+    if (process.env.CK_DEBUG) {
+      console.error(`[CK] Failed to create ${dirPath}: ${err.message}`);
+    }
+  }
+}
+
+/**
+ * Get marker file path for a session
+ * @param {string} sessionId - Session ID
+ * @returns {string} Full path to marker file
+ */
+function getMarkerPath(sessionId) {
+  return path.join(MARKERS_DIR, `${sessionId}.json`);
+}
+
+/**
+ * Get debug log path for a session
+ * @param {string} sessionId - Session ID
+ * @returns {string} Full path to debug log
+ */
+function getDebugLogPath(sessionId) {
+  return path.join(DEBUG_DIR, `${sessionId}.log`);
+}
+
+/**
+ * Initialize ClaudeKit temp directories
+ * Call this at startup to ensure directories exist
+ */
+function initDirs() {
+  ensureDir(CK_TMP_DIR);
+  ensureDir(MARKERS_DIR);
+  ensureDir(DEBUG_DIR);
+}
+
+/**
+ * Clean up all ClaudeKit temp files
+ * Useful for testing or manual cleanup
+ */
+function cleanAll() {
+  try {
+    if (fs.existsSync(CK_TMP_DIR)) {
+      fs.rmSync(CK_TMP_DIR, { recursive: true, force: true });
+    }
+  } catch (err) {
+    // Silent fail
+  }
+}
+
+module.exports = {
+  // Directories
+  CK_TMP_DIR,
+  MARKERS_DIR,
+  DEBUG_DIR,
+
+  // Files
+  CALIBRATION_PATH,
+
+  // Helpers
+  ensureDir,
+  getMarkerPath,
+  getDebugLogPath,
+  initDirs,
+  cleanAll
+};

package/templates/hooks/lib/context-tracker.cjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Context Window Tracker - Self-healing context reset detection
+ *
+ * Fixes #177: Race condition from shared global state file
+ * Fixes #178: Consolidates temp files to /tmp/ck/ namespace
+ *
+ * Architecture:
+ * - NO global state file (was causing race conditions in concurrent sessions)
+ * - All state embedded in session-specific marker files
+ * - Each session is completely isolated (no shared state)
+ *
+ * Detection layers:
+ * - Layer 1: Hook markers (explicit reset signal from PreCompact/SessionStart)
+ * - Layer 2: Token drop detection (50% threshold fallback for hook failures)
+ *
+ * Removed:
+ * - Old Layer 1 (session ID change detection) - was the BUG source
+ * - Global STATE_FILE - caused race conditions in concurrent sessions
+ *
+ * Marker schema:
+ * {
+ *   sessionId: string,
+ *   trigger: string,           // 'session_start_clear', 'manual', 'auto', 'new_session', 'token_drop'
+ *   baselineRecorded: boolean,
+ *   baseline: number,          // Token count at baseline
+ *   lastTokenTotal: number,    // For token drop detection (replaces global state)
+ *   timestamp: number
+ * }
+ *
+ * @module context-tracker
+ */
+
+const fs = require('fs');
+const {
+  MARKERS_DIR,
+  CALIBRATION_PATH,
+  ensureDir,
+  getMarkerPath
+} = require('./ck-paths.cjs');
+
+// Token drop threshold for Layer 2 detection (50%)
+// Rationale: /compact typically reduces tokens by 60-80%, so 50% catches
+// context resets while avoiding false positives from normal token accumulation.
+// Exclusive: drops below (<) 50% trigger reset
+const TOKEN_DROP_THRESHOLD = 0.5;
+
+/**
+ * Get smart default compact threshold based on context window size
+ * Research-based defaults:
+ * - 200k window: ~77.5% (155k) - confirmed from GitHub issues
+ * - 1M window: ~33% (330k) - derived from user observations
+ *
+ * @param {number} contextWindowSize - Model's context window size
+ * @returns {number} Estimated compact threshold in tokens
+ */
+function getDefaultCompactThreshold(contextWindowSize) {
+  const KNOWN_THRESHOLDS = {
+    200000: 155000,   // 77.5% - confirmed via /context showing 45k buffer
+    1000000: 330000,  // 33% - 1M beta window
+  };
+
+  if (KNOWN_THRESHOLDS[contextWindowSize]) {
+    return KNOWN_THRESHOLDS[contextWindowSize];
+  }
+
+  // Tiered defaults based on window size
+  if (contextWindowSize >= 1000000) {
+    return Math.floor(contextWindowSize * 0.33);
+  }
+  return Math.floor(contextWindowSize * 0.775);
+}
+
+/**
+ * Read calibration data from file (recorded by PreCompact hook)
+ * @returns {Object} Calibration data keyed by context window size
+ */
+function readCalibration() {
+  try {
+    if (fs.existsSync(CALIBRATION_PATH)) {
+      return JSON.parse(fs.readFileSync(CALIBRATION_PATH, 'utf8'));
+    }
+  } catch (err) {
+    // Silent fail - use defaults
+  }
+  return {};
+}
+
+/**
+ * Get compact threshold, preferring calibrated value over default
+ * @param {number} contextWindowSize - Model's context window size
+ * @returns {number} Compact threshold in tokens
+ */
+function getCompactThreshold(contextWindowSize) {
+  const calibration = readCalibration();
+  const key = String(contextWindowSize);
+
+  if (calibration[key] && calibration[key].threshold > 0) {
+    return calibration[key].threshold;
+  }
+  return getDefaultCompactThreshold(contextWindowSize);
+}
+
+/**
+ * Read marker file for a session
+ * Defensive: handles missing/empty/corrupt files gracefully
+ * @param {string} sessionId - Session ID
+ * @returns {Object|null} Marker data or null
+ */
+function readMarker(sessionId) {
+  try {
+    const markerPath = getMarkerPath(sessionId);
+    if (!fs.existsSync(markerPath)) return null;
+    const data = fs.readFileSync(markerPath, 'utf8');
+    if (!data.trim()) return null; // Catch empty/corrupt files
+    const marker = JSON.parse(data);
+    // Basic schema validation
+    if (!marker || typeof marker.sessionId !== 'string') {
+      return null;
+    }
+    return marker;
+  } catch (err) {
+    // Silent fail - corrupt JSON or read error
+  }
+  return null;
+}
+
+/**
+ * Write marker file for a session
+ * @param {string} sessionId - Session ID
+ * @param {Object} marker - Marker data
+ */
+function writeMarker(sessionId, marker) {
+  try {
+    ensureDir(MARKERS_DIR);
+    const markerPath = getMarkerPath(sessionId);
+    fs.writeFileSync(markerPath, JSON.stringify(marker));
+  } catch (err) {
+    // Silent fail
+  }
+}
+
+/**
+ * Delete marker file for a session
+ * @param {string} sessionId - Session ID
+ */
+function deleteMarker(sessionId) {
+  try {
+    const markerPath = getMarkerPath(sessionId);
+    if (fs.existsSync(markerPath)) {
+      fs.unlinkSync(markerPath);
+    }
+  } catch (err) {
+    // Silent fail
+  }
+}
+
+/**
+ * Layer 2: Detect significant token drop (50%+ reduction)
+ * Uses session-specific lastTokenTotal from marker (no global state)
+ * @param {number} currentTotal - Current cumulative token total
+ * @param {Object|null} marker - Session marker with lastTokenTotal
+ * @returns {boolean} True if token drop detected
+ */
+function detectTokenDrop(currentTotal, marker) {
+  if (!marker || !marker.lastTokenTotal || marker.lastTokenTotal <= 0 || currentTotal <= 0) {
+    return false;
+  }
+
+  // Token total dropped by more than 50%
+  const dropRatio = currentTotal / marker.lastTokenTotal;
+  return dropRatio < TOKEN_DROP_THRESHOLD;
+}
+
+/**
+ * Layer 1: Check for explicit reset marker from hooks
+ * @param {Object|null} marker - Session marker
+ * @returns {{ shouldReset: boolean, trigger: string|null }}
+ */
+function checkResetMarker(marker) {
+  if (!marker) {
+    return { shouldReset: false, trigger: null };
+  }
+
+  // Check if marker indicates a reset (clear/compact)
+  const resetTriggers = ['clear', 'session_start_clear'];
+  if (resetTriggers.includes(marker.trigger)) {
+    return { shouldReset: true, trigger: marker.trigger };
+  }
+
+  return { shouldReset: false, trigger: marker.trigger };
+}
+
+/**
+ * Main context tracking function with 2-layer self-healing detection
+ *
+ * Layer 1: Hook markers (explicit reset from PreCompact/SessionStart)
+ * Layer 2: Token drop detection (50% threshold fallback)
+ *
+ * NO global state - all state is session-specific in marker files
+ *
+ * @param {Object} params - Tracking parameters
+ * @param {string} params.sessionId - Current session ID
+ * @param {number} params.contextInput - Input tokens
+ * @param {number} params.contextOutput - Output tokens
+ * @param {number} params.contextWindowSize - Model's context window size
+ * @returns {Object} { percentage, baseline, showCompactIndicator, resetLayer }
+ */
+function trackContext({ sessionId, contextInput, contextOutput, contextWindowSize }) {
+  const currentTotal = contextInput + contextOutput;
+  const compactThreshold = getCompactThreshold(contextWindowSize);
+  const effectiveSessionId = sessionId || 'default';
+
+  // Read session-specific marker (no global state!)
+  let marker = readMarker(effectiveSessionId);
+
+  // Track which layer triggered reset (for debugging)
+  let resetLayer = null;
+  let baseline = 0;
+  let showCompactIndicator = false;
+
+  // --- Layer 1: Hook marker system ---
+  // Markers from PreCompact/SessionStart hooks are explicit signals
+  const { shouldReset, trigger } = checkResetMarker(marker);
+  if (shouldReset) {
+    resetLayer = `marker_${trigger}`;
+    baseline = currentTotal;
+    // Clear the reset trigger after processing
+    marker = null; // Force fresh marker creation below
+  }
+
+  // --- Layer 2: Token drop detection (fallback for hook failures) ---
+  if (!resetLayer && detectTokenDrop(currentTotal, marker)) {
+    resetLayer = 'token_drop';
+    baseline = currentTotal;
+    marker = null; // Force fresh marker creation below
+  }
+
+  // --- No reset triggered - use existing marker/baseline ---
+  if (!resetLayer && marker) {
+    if (!marker.baselineRecorded) {
+      // Marker exists but baseline not recorded yet (from PreCompact)
+      marker.baselineRecorded = true;
+      marker.baseline = currentTotal;
+      marker.lastTokenTotal = currentTotal;
+      writeMarker(effectiveSessionId, marker);
+      baseline = currentTotal;
+      // PreCompact triggers: "manual" (from /compact) or "auto" (from auto-compact)
+      showCompactIndicator = ['compact', 'manual', 'auto'].includes(marker.trigger);
+    } else {
+      // Use stored baseline
+      baseline = marker.baseline || 0;
+    }
+  }
+
+  // --- Create fresh marker if needed ---
+  if (!marker || resetLayer) {
+    const newMarker = {
+      sessionId: effectiveSessionId,
+      trigger: resetLayer || 'new_session',
+      baselineRecorded: true,
+      baseline: currentTotal,
+      lastTokenTotal: currentTotal,
+      timestamp: Date.now()
+    };
+    writeMarker(effectiveSessionId, newMarker);
+    if (!resetLayer) {
+      baseline = currentTotal;
+    }
+  } else {
+    // Update lastTokenTotal for next token drop detection
+    marker.lastTokenTotal = currentTotal;
+    writeMarker(effectiveSessionId, marker);
+  }
+
+  // Calculate effective tokens (since baseline)
+  let effectiveTotal = baseline > 0 ? currentTotal - baseline : currentTotal;
+  if (effectiveTotal < 0) effectiveTotal = 0;
+
+  // Calculate percentage against compact threshold (not model limit)
+  const percentage = Math.min(100, Math.floor(effectiveTotal * 100 / compactThreshold));
+
+  return {
+    percentage,
+    baseline,
+    effectiveTotal,
+    compactThreshold,
+    showCompactIndicator,
+    resetLayer
+  };
+}
+
+/**
+ * Write reset marker for session (called by SessionStart hook on /clear)
+ * @param {string} sessionId - Session ID
+ * @param {string} trigger - Reset trigger ('clear', 'compact', etc.)
+ */
+function writeResetMarker(sessionId, trigger = 'clear') {
+  const effectiveSessionId = sessionId || 'default';
+  ensureDir(MARKERS_DIR);
+  writeMarker(effectiveSessionId, {
+    sessionId: effectiveSessionId,
+    trigger: `session_start_${trigger}`,
+    baselineRecorded: false,
+    baseline: 0,
+    lastTokenTotal: 0,
+    timestamp: Date.now()
+  });
+}
+
+/**
+ * Clear all markers (for testing/cleanup)
+ * Uses new /tmp/ck/ namespace
+ */
+function clearAllState() {
+  const { cleanAll } = require('./ck-paths.cjs');
+  cleanAll();
+}
+
+module.exports = {
+  trackContext,
+  writeResetMarker,
+  clearAllState,
+  getCompactThreshold,
+  // Export for testing
+  detectTokenDrop,
+  checkResetMarker,
+  readMarker,
+  writeMarker,
+  deleteMarker,
+  TOKEN_DROP_THRESHOLD,
+  MARKERS_DIR
+};

package/templates/hooks/notifications/.env.example

@@ -0,0 +1,21 @@
+# Notification Providers - Set credentials for providers you want to use
+# Env loading priority: process.env > ~/.claude/.env > .claude/.env
+
+# ============================================
+# Telegram Notifications
+# ============================================
+# Get token from @BotFather, chat_id from getUpdates API
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=
+
+# ============================================
+# Discord Notifications
+# ============================================
+# Create webhook: Server Settings > Integrations > Webhooks
+DISCORD_WEBHOOK_URL=
+
+# ============================================
+# Slack Notifications (NEW)
+# ============================================
+# Create app at api.slack.com/apps, enable Incoming Webhooks
+SLACK_WEBHOOK_URL=

package/templates/hooks/notifications/discord_notify.sh

@@ -0,0 +1,221 @@
+#!/bin/bash
+
+# Discord Notification Hook for Claude Code
+# This hook sends a notification to Discord when Claude finishes a task
+
+set -euo pipefail
+
+# Load environment variables with priority: process.env > .claude/.env > .claude/hooks/.env
+load_env() {
+    # 1. Start with lowest priority: .claude/hooks/.env
+    if [[ -f "$(dirname "$0")/.env" ]]; then
+        set -a
+        source "$(dirname "$0")/.env"
+        set +a
+    fi
+
+    # 2. Override with .claude/.env
+    if [[ -f .claude/.env ]]; then
+        set -a
+        source .claude/.env
+        set +a
+    fi
+
+    # 3. Process env (already loaded) has highest priority - no action needed
+    # Variables already in process.env will not be overwritten by 'source'
+}
+
+load_env
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Extract relevant information from the hook input
+HOOK_TYPE=$(echo "$INPUT" | jq -r '.hookType // "unknown"')
+PROJECT_DIR=$(echo "$INPUT" | jq -r '.projectDir // ""')
+TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+SESSION_ID=$(echo "$INPUT" | jq -r '.sessionId // ""')
+PROJECT_NAME=$(basename "$PROJECT_DIR")
+
+# Configuration - these will be set via environment variables
+DISCORD_WEBHOOK_URL="${DISCORD_WEBHOOK_URL:-}"
+
+# Validate required environment variables
+if [[ -z "$DISCORD_WEBHOOK_URL" ]]; then
+    echo "⚠️  Discord notification skipped: DISCORD_WEBHOOK_URL not set" >&2
+    exit 0
+fi
+
+# Function to send Discord message with embeds
+send_discord_embed() {
+    local title="$1"
+    local description="$2"
+    local color="$3"
+    local fields="$4"
+
+    local payload=$(cat <<EOF
+{
+    "embeds": [{
+        "title": "$title",
+        "description": "$description",
+        "color": $color,
+        "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)",
+        "footer": {
+            "text": "Project Name • ${PROJECT_NAME}"
+        },
+        "fields": $fields
+    }]
+}
+EOF
+)
+
+    curl -s -X POST "$DISCORD_WEBHOOK_URL" \
+        -H "Content-Type: application/json" \
+        -d "$payload" > /dev/null 2>&1
+}
+
+# Generate summary based on hook type
+case "$HOOK_TYPE" in
+    "Stop")
+        # Extract tool usage summary
+        TOOLS_USED=$(echo "$INPUT" | jq -r '.toolsUsed[]?.tool // empty' | sort | uniq -c | sort -nr)
+        FILES_MODIFIED=$(echo "$INPUT" | jq -r '.toolsUsed[]? | select(.tool == "Edit" or .tool == "Write" or .tool == "MultiEdit") | .parameters.file_path // empty' | sort | uniq)
+
+        # Count operations
+        TOTAL_TOOLS=$(echo "$INPUT" | jq '.toolsUsed | length')
+
+        # Build description
+        DESCRIPTION="✅ Claude Code session completed successfully"
+
+        # Build tools used text
+        TOOLS_TEXT=""
+        if [[ -n "$TOOLS_USED" ]]; then
+            TOOLS_TEXT=$(echo "$TOOLS_USED" | while read count tool; do
+                echo "• **${count}** ${tool}"
+            done | paste -sd '\n' -)
+        else
+            TOOLS_TEXT="No tools used"
+        fi
+
+        # Build files modified text
+        FILES_TEXT=""
+        if [[ -n "$FILES_MODIFIED" ]]; then
+            FILES_TEXT=$(echo "$FILES_MODIFIED" | while IFS= read -r file; do
+                if [[ -n "$file" ]]; then
+                    relative_file=$(echo "$file" | sed "s|^${PROJECT_DIR}/||")
+                    echo "• \`${relative_file}\`"
+                fi
+            done | paste -sd '\n' -)
+        else
+            FILES_TEXT="No files modified"
+        fi
+
+        # Build fields JSON
+        FIELDS=$(cat <<EOF
+[
+    {
+        "name": "⏰ Session Time",
+        "value": "${TIMESTAMP}",
+        "inline": true
+    },
+    {
+        "name": "🔧 Total Operations",
+        "value": "${TOTAL_TOOLS}",
+        "inline": true
+    },
+    {
+        "name": "🆔 Session ID",
+        "value": "\`${SESSION_ID:0:8}...\`",
+        "inline": true
+    },
+    {
+        "name": "📦 Tools Used",
+        "value": "${TOOLS_TEXT}",
+        "inline": false
+    },
+    {
+        "name": "📝 Files Modified",
+        "value": "${FILES_TEXT}",
+        "inline": false
+    },
+    {
+        "name": "📍 Location",
+        "value": "\`${PROJECT_DIR}\`",
+        "inline": false
+    }
+]
+EOF
+)
+
+        send_discord_embed "🤖 Claude Code Session Complete" "$DESCRIPTION" 5763719 "$FIELDS"
+        ;;
+
+    "SubagentStop")
+        SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.subagentType // "unknown"')
+
+        DESCRIPTION="Specialized agent completed its task"
+
+        FIELDS=$(cat <<EOF
+[
+    {
+        "name": "⏰ Time",
+        "value": "${TIMESTAMP}",
+        "inline": true
+    },
+    {
+        "name": "🔧 Agent Type",
+        "value": "${SUBAGENT_TYPE}",
+        "inline": true
+    },
+    {
+        "name": "🆔 Session ID",
+        "value": "\`${SESSION_ID:0:8}...\`",
+        "inline": true
+    },
+    {
+        "name": "📍 Location",
+        "value": "\`${PROJECT_DIR}\`",
+        "inline": false
+    }
+]
+EOF
+)
+
+        send_discord_embed "🎯 Claude Code Subagent Complete" "$DESCRIPTION" 3447003 "$FIELDS"
+        ;;
+
+    *)
+        DESCRIPTION="Claude Code event triggered"
+
+        FIELDS=$(cat <<EOF
+[
+    {
+        "name": "⏰ Time",
+        "value": "${TIMESTAMP}",
+        "inline": true
+    },
+    {
+        "name": "📋 Event Type",
+        "value": "${HOOK_TYPE}",
+        "inline": true
+    },
+    {
+        "name": "🆔 Session ID",
+        "value": "\`${SESSION_ID:0:8}...\`",
+        "inline": true
+    },
+    {
+        "name": "📍 Location",
+        "value": "\`${PROJECT_DIR}\`",
+        "inline": false
+    }
+]
+EOF
+)
+
+        send_discord_embed "📝 Claude Code Event" "$DESCRIPTION" 10070709 "$FIELDS"
+        ;;
+esac
+
+# Log the notification (optional)
+echo "✅ Discord notification sent for $HOOK_TYPE event in project $PROJECT_NAME" >&2