@stella-studio/ck 1.0.0

package/.claude/hooks/notifications/providers/telegram.cjs

@@ -0,0 +1,109 @@
+/**
+ * Telegram notification provider
+ * Ported from telegram_notify.sh - uses Telegram Bot API
+ */
+'use strict';
+
+const path = require('path');
+const { send } = require('../lib/sender.cjs');
+
+/**
+ * Format timestamp as YYYY-MM-DD HH:MM:SS
+ * @returns {string}
+ */
+function getTimestamp() {
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ` +
+         `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+}
+
+/**
+ * Format message based on hook event type
+ * Matches bash script output format exactly
+ * @param {Object} input - Hook input with snake_case fields
+ * @returns {string} Markdown-formatted message
+ */
+function formatMessage(input) {
+  const hookType = input.hook_event_name || 'unknown';
+  const projectDir = input.cwd || '';
+  const sessionId = input.session_id || '';
+  const projectName = projectDir ? path.basename(projectDir) : 'unknown';
+  const timestamp = getTimestamp();
+  const sessionDisplay = sessionId ? `${sessionId.slice(0, 8)}...` : 'N/A';
+
+  switch (hookType) {
+    case 'Stop':
+      return `🚀 *Project Task Completed*
+
+📅 *Time:* ${timestamp}
+📁 *Project:* ${projectName}
+🆔 *Session:* ${sessionDisplay}
+
+📍 *Location:* \`${projectDir}\``;
+
+    case 'SubagentStop': {
+      const agentType = input.agent_type || 'unknown';
+      return `🤖 *Project Subagent Completed*
+
+📅 *Time:* ${timestamp}
+📁 *Project:* ${projectName}
+🔧 *Agent Type:* ${agentType}
+🆔 *Session:* ${sessionDisplay}
+
+Specialized agent completed its task.
+
+📍 *Location:* \`${projectDir}\``;
+    }
+
+    case 'AskUserPrompt':
+      return `💬 *User Input Needed*
+
+📅 *Time:* ${timestamp}
+📁 *Project:* ${projectName}
+🆔 *Session:* ${sessionDisplay}
+
+Claude is waiting for your input.
+
+📍 *Location:* \`${projectDir}\``;
+
+    default:
+      return `📝 *Project Code Event*
+
+📅 *Time:* ${timestamp}
+📁 *Project:* ${projectName}
+📋 *Event:* ${hookType}
+🆔 *Session:* ${sessionDisplay}
+
+📍 *Location:* \`${projectDir}\``;
+  }
+}
+
+module.exports = {
+  name: 'telegram',
+
+  /**
+   * Check if Telegram provider is enabled
+   * @param {Object} env - Environment variables
+   * @returns {boolean}
+   */
+  isEnabled: (env) => !!(env.TELEGRAM_BOT_TOKEN && env.TELEGRAM_CHAT_ID),
+
+  /**
+   * Send notification to Telegram
+   * @param {Object} input - Hook input data (snake_case fields)
+   * @param {Object} env - Environment variables
+   * @returns {Promise<{success: boolean, error?: string, throttled?: boolean}>}
+   */
+  send: async (input, env) => {
+    const message = formatMessage(input);
+    const url = `https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/sendMessage`;
+
+    return send('telegram', url, {
+      chat_id: env.TELEGRAM_CHAT_ID,
+      text: message,
+      parse_mode: 'Markdown',
+      disable_web_page_preview: true
+    });
+  }
+};

package/.claude/hooks/notifications/send-discord.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+
+# Usage: ./send-discord.sh 'Your message here'
+# Note: Remember to escape the string
+
+# 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
+
+message="$1"
+    
+if [[ -z "$DISCORD_WEBHOOK_URL" ]]; then
+    echo "⚠️  Discord notification skipped: DISCORD_WEBHOOK_URL not set"
+    exit 1
+fi
+
+# Prepare message for Discord (Discord markdown supports \n)
+discord_message="$message"
+
+# Discord embeds for richer formatting
+payload=$(cat <<EOF
+{
+"embeds": [{
+    "title": "🤖 Claude Code Session Complete",
+    "description": "$discord_message",
+    "color": 5763719,
+    "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)",
+    "footer": {
+        "text": "Project Name • $(basename "$(pwd)")"
+    },
+    "fields": [
+        {
+            "name": "⏰ Session Time",
+            "value": "$(date '+%H:%M:%S')",
+            "inline": true
+        },
+        {
+            "name": "📂 Project",
+            "value": "$(basename "$(pwd)")",
+            "inline": true
+        }
+    ]
+}]
+}
+EOF
+)
+
+curl -s -X POST "$DISCORD_WEBHOOK_URL" \
+    -H "Content-Type: application/json" \
+    -d "$payload" >/dev/null 2>&1
+
+if [[ $? -eq 0 ]]; then
+    echo "✅ Discord notification sent"
+else
+    echo "❌ Failed to send Discord notification"
+    exit 1
+fi

package/.claude/hooks/notifications/telegram_notify.sh

@@ -0,0 +1,137 @@
+#!/bin/bash
+
+# ┌─────────────────────────────────────────────────────────────────────────┐
+# │ DEPRECATED: This script is no longer maintained                         │
+# │                                                                         │
+# │ Use notify.cjs instead - zero dependencies, works everywhere:           │
+# │   node .claude/hooks/notifications/notify.cjs                           │
+# │                                                                         │
+# │ In your settings.json:                                                  │
+# │   "Stop": [{"matcher": "*", "hooks": [{"type": "command",               │
+# │     "command": "node .claude/hooks/notifications/notify.cjs"}]}]        │
+# └─────────────────────────────────────────────────────────────────────────┘
+
+echo "⚠️  DEPRECATED: telegram_notify.sh is no longer maintained" >&2
+echo "   Use: node .claude/hooks/notifications/notify.cjs" >&2
+echo "   See: .claude/hooks/notifications/docs/" >&2
+exit 1
+
+# --- LEGACY CODE BELOW (kept for reference) ---
+
+# 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
+# Note: Claude Code hooks use snake_case field names
+HOOK_TYPE=$(echo "$INPUT" | jq -r '.hook_event_name // "unknown"')
+PROJECT_DIR=$(echo "$INPUT" | jq -r '.cwd // ""')
+TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // ""')
+PROJECT_NAME=$(basename "$PROJECT_DIR")
+
+# Configuration - these will be set via environment variables
+TELEGRAM_BOT_TOKEN="${TELEGRAM_BOT_TOKEN:-}"
+TELEGRAM_CHAT_ID="${TELEGRAM_CHAT_ID:-}"
+
+# Validate required environment variables
+if [[ -z "$TELEGRAM_BOT_TOKEN" ]]; then
+    echo "Error: TELEGRAM_BOT_TOKEN environment variable not set" >&2
+    exit 1
+fi
+
+if [[ -z "$TELEGRAM_CHAT_ID" ]]; then
+    echo "Error: TELEGRAM_CHAT_ID environment variable not set" >&2
+    exit 1
+fi
+
+# Function to send Telegram message
+send_telegram_message() {
+    local message="$1"
+    local url="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage"
+    
+    # Escape special characters for JSON
+    local escaped_message=$(echo "$message" | jq -Rs .)
+    
+    local payload=$(cat <<EOF
+{
+    "chat_id": "${TELEGRAM_CHAT_ID}",
+    "text": ${escaped_message},
+    "parse_mode": "Markdown",
+    "disable_web_page_preview": true
+}
+EOF
+)
+    
+    curl -s -X POST \
+        -H "Content-Type: application/json" \
+        -d "$payload" \
+        "$url" > /dev/null
+}
+
+# Generate summary based on hook type
+# Note: Stop/SubagentStop hooks do not include tool usage data
+case "$HOOK_TYPE" in
+    "Stop")
+        # Build summary message
+        MESSAGE="🚀 *Project Task Completed*
+
+📅 *Time:* ${TIMESTAMP}
+📁 *Project:* ${PROJECT_NAME}
+🆔 *Session:* ${SESSION_ID:0:8}...
+
+📍 *Location:* \`${PROJECT_DIR}\`"
+        ;;
+        
+    "SubagentStop")
+        SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.agent_type // "unknown"')
+        MESSAGE="🤖 *Project Subagent Completed*
+
+📅 *Time:* ${TIMESTAMP}
+📁 *Project:* ${PROJECT_NAME}
+🔧 *Agent Type:* ${SUBAGENT_TYPE}
+🆔 *Session:* ${SESSION_ID:0:8}...
+
+Specialized agent completed its task.
+
+📍 *Location:* \`${PROJECT_DIR}\`"
+        ;;
+        
+    *)
+        MESSAGE="📝 *Project Code Event*
+
+📅 *Time:* ${TIMESTAMP}
+📁 *Project:* ${PROJECT_NAME}
+📋 *Event:* ${HOOK_TYPE}
+🆔 *Session:* ${SESSION_ID:0:8}...
+
+📍 *Location:* \`${PROJECT_DIR}\`"
+        ;;
+esac
+
+# Send the notification
+send_telegram_message "$MESSAGE"
+
+# Log the notification (optional)
+echo "Telegram notification sent for $HOOK_TYPE event in project $PROJECT_NAME" >&2

package/.claude/hooks/post-edit-simplify-reminder.cjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook: Tracks file modifications and reminds to run code-simplifier
+ *
+ * This hook fires after Edit/Write/MultiEdit operations and:
+ * 1. Tracks modified files in the session
+ * 2. After significant edits, injects a reminder to run code-simplifier
+ *
+ * Auto-trigger behavior:
+ * - Tracks edit count per session
+ * - After 5+ file edits, reminds about code-simplifier
+ * - Resets counter when simplifier is mentioned in conversation
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { isHookEnabled } = require('./lib/ck-config-utils.cjs');
+
+// Early exit if hook disabled in config
+if (!isHookEnabled('post-edit-simplify-reminder')) {
+  process.exit(0);
+}
+
+// Session tracking file
+const SESSION_TRACK_FILE = path.join(os.tmpdir(), 'ck-simplify-session.json');
+const EDIT_THRESHOLD = 5; // Remind after this many edits
+
+/**
+ * Load or initialize session tracking data
+ */
+function loadSessionData() {
+  try {
+    if (fs.existsSync(SESSION_TRACK_FILE)) {
+      const data = JSON.parse(fs.readFileSync(SESSION_TRACK_FILE, 'utf8'));
+      // Reset if session is older than 2 hours
+      if (Date.now() - data.startTime > 2 * 60 * 60 * 1000) {
+        return initSessionData();
+      }
+      return data;
+    }
+  } catch (e) {
+    // Ignore errors, reinitialize
+  }
+  return initSessionData();
+}
+
+/**
+ * Initialize fresh session data
+ */
+function initSessionData() {
+  return {
+    startTime: Date.now(),
+    editCount: 0,
+    modifiedFiles: [],
+    lastReminder: 0,
+    simplifierRun: false
+  };
+}
+
+/**
+ * Save session tracking data
+ */
+function saveSessionData(data) {
+  try {
+    fs.writeFileSync(SESSION_TRACK_FILE, JSON.stringify(data, null, 2));
+  } catch (e) {
+    // Ignore write errors
+  }
+}
+
+/**
+ * Main hook logic
+ */
+function main() {
+  try {
+    // Read hook input from stdin
+    let input = '';
+    const stdin = fs.readFileSync(0, 'utf8');
+    if (stdin) {
+      input = stdin;
+    }
+
+    const hookData = JSON.parse(input || '{}');
+    const toolName = hookData.tool_name || '';
+    const toolInput = hookData.tool_input || {};
+
+    // Only track edit operations
+    const editTools = ['Edit', 'Write', 'MultiEdit'];
+    if (!editTools.includes(toolName)) {
+      // Pass through without modification
+      console.log(JSON.stringify({ continue: true }));
+      return;
+    }
+
+    // Load session data
+    const session = loadSessionData();
+
+    // Track the edit
+    session.editCount++;
+    const filePath = toolInput.file_path || toolInput.path || '';
+    if (filePath && !session.modifiedFiles.includes(filePath)) {
+      session.modifiedFiles.push(filePath);
+    }
+
+    // Check if we should remind about code-simplifier
+    const shouldRemind =
+      session.editCount >= EDIT_THRESHOLD &&
+      !session.simplifierRun &&
+      (Date.now() - session.lastReminder > 10 * 60 * 1000); // Don't remind more than every 10 min
+
+    let additionalContext = '';
+    if (shouldRemind) {
+      session.lastReminder = Date.now();
+      additionalContext = `\n\n[Code Simplification Reminder] You have modified ${session.modifiedFiles.length} files in this session. Consider using the \`code-simplifier\` agent to refine recent changes before proceeding to code review. This is a MANDATORY step in the workflow.`;
+    }
+
+    // Save updated session data
+    saveSessionData(session);
+
+    // Output hook result
+    const result = {
+      continue: true
+    };
+
+    if (additionalContext) {
+      result.additionalContext = additionalContext;
+    }
+
+    console.log(JSON.stringify(result));
+
+  } catch (e) {
+    // On error, allow the operation to continue
+    console.log(JSON.stringify({ continue: true }));
+  }
+}
+
+main();

package/.claude/hooks/privacy-block.cjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * privacy-block.cjs - Block access to sensitive files unless user-approved
+ *
+ * PRIVACY-based blocking (separate from SIZE-based scout-block)
+ * Blocks sensitive files. LLM must get user approval and use APPROVED: prefix.
+ *
+ * Flow:
+ * 1. LLM tries: Read ".env" → BLOCKED
+ * 2. LLM asks user for permission
+ * 3. User approves
+ * 4. LLM retries: Read "APPROVED:.env" → ALLOWED
+ *
+ * Core logic extracted to lib/privacy-checker.cjs for OpenCode plugin reuse.
+ */
+
+const path = require('path');
+
+// Import shared privacy checking logic
+const {
+  checkPrivacy,
+  isSafeFile,
+  isPrivacyBlockDisabled,
+  isPrivacySensitive,
+  hasApprovalPrefix,
+  stripApprovalPrefix,
+  extractPaths,
+  isSuspiciousPath
+} = require('./lib/privacy-checker.cjs');
+const { isHookEnabled } = require('./lib/ck-config-utils.cjs');
+
+// Early exit if hook disabled in config
+if (!isHookEnabled('privacy-block')) {
+  process.exit(0);
+}
+
+/**
+ * Format block message with approval instructions and JSON marker for AskUserQuestion
+ * @param {string} filePath - Blocked file path
+ * @returns {string} Formatted block message with JSON marker
+ */
+function formatBlockMessage(filePath) {
+  const basename = path.basename(filePath);
+
+  // JSON marker for LLM to parse and use AskUserQuestion tool
+  const promptData = {
+    type: 'PRIVACY_PROMPT',
+    file: filePath,
+    basename: basename,
+    question: {
+      header: 'File Access',
+      text: `I need to read "${basename}" which may contain sensitive data (API keys, passwords, tokens). Do you approve?`,
+      options: [
+        { label: 'Yes, approve access', description: `Allow reading ${basename} this time` },
+        { label: 'No, skip this file', description: 'Continue without accessing this file' }
+      ]
+    }
+  };
+
+  return `
+\x1b[36mNOTE:\x1b[0m This is not an error - this block protects sensitive data.
+
+\x1b[33mPRIVACY BLOCK\x1b[0m: Sensitive file access requires user approval
+
+  \x1b[33mFile:\x1b[0m ${filePath}
+
+  This file may contain secrets (API keys, passwords, tokens).
+
+\x1b[90m@@PRIVACY_PROMPT_START@@\x1b[0m
+${JSON.stringify(promptData, null, 2)}
+\x1b[90m@@PRIVACY_PROMPT_END@@\x1b[0m
+
+  \x1b[34mClaude:\x1b[0m Use AskUserQuestion tool with the JSON above, then:
+  \x1b[32mIf "Yes":\x1b[0m Use bash to read: cat "${filePath}"
+  \x1b[31mIf "No":\x1b[0m  Continue without this file.
+`;
+}
+
+/**
+ * Format approval notice
+ * @param {string} filePath - Approved file path
+ * @returns {string} Formatted approval notice
+ */
+function formatApprovalNotice(filePath) {
+  return `\x1b[32m✓\x1b[0m Privacy: User-approved access to ${path.basename(filePath)}`;
+}
+
+// Main
+async function main() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let hookData;
+  try {
+    hookData = JSON.parse(input);
+  } catch (e) {
+    process.exit(0); // Invalid JSON, allow
+  }
+
+  const { tool_input: toolInput, tool_name: toolName } = hookData;
+
+  // Use shared privacy checker
+  const result = checkPrivacy({
+    toolName,
+    toolInput,
+    options: { allowBash: true }
+  });
+
+  // Handle results
+  if (result.approved) {
+    // User approved - allow with notice
+    if (result.suspicious) {
+      console.error('\x1b[33mWARN:\x1b[0m Approved path is outside project:', result.filePath);
+    }
+    console.error(formatApprovalNotice(result.filePath));
+    process.exit(0);
+  }
+
+  if (result.isBash) {
+    // Bash: warn but don't block - allows "Yes → bash cat" flow
+    console.error(`\x1b[33mWARN:\x1b[0m ${result.reason}`);
+    process.exit(0);
+  }
+
+  if (result.blocked) {
+    // No approval - block
+    console.error(formatBlockMessage(result.filePath));
+    process.exit(2);
+  }
+
+  process.exit(0); // Allow
+}
+
+// Run main only when executed directly (not when required for testing)
+if (require.main === module) {
+  main().catch(() => process.exit(0));
+}
+
+// Export functions for unit testing
+if (typeof module !== 'undefined') {
+  module.exports = {
+    isSafeFile,
+    isPrivacyBlockDisabled,
+    isPrivacySensitive,
+    hasApprovalPrefix,
+    stripApprovalPrefix,
+    extractPaths,
+  };
+}