@macpaw/cctk 1.0.0-beta.1

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

@@ -0,0 +1,289 @@
+#!/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
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const APPROVED_PREFIX = 'APPROVED:';
+
+// Safe file patterns - exempt from privacy checks (documentation/template files)
+const SAFE_PATTERNS = [
+  /\.example$/i,   // .env.example, config.example
+  /\.sample$/i,    // .env.sample
+  /\.template$/i,  // .env.template
+];
+
+// Privacy-sensitive patterns
+const PRIVACY_PATTERNS = [
+  /^\.env$/,              // .env
+  /^\.env\./,             // .env.local, .env.production, etc.
+  /\.env$/,               // path/to/.env
+  /\/\.env\./,            // path/to/.env.local
+  /credentials/i,         // credentials.json, etc.
+  /secrets?\.ya?ml$/i,    // secrets.yaml, secret.yml
+  /\.pem$/,               // Private keys
+  /\.key$/,               // Private keys
+  /id_rsa/,               // SSH keys
+  /id_ed25519/,           // SSH keys
+];
+
+/**
+ * Load .cctk.json config to check if privacy block is disabled
+ * @returns {boolean} true if privacy block should be skipped
+ */
+function isPrivacyBlockDisabled() {
+  try {
+    const configPath = path.join(process.cwd(), '.claude', '.cctk.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return config.privacyBlock === false;
+  } catch {
+    return false; // Default to enabled on error (file not found or invalid JSON)
+  }
+}
+
+/**
+ * Check if path is a safe file (example/sample/template)
+ * @param {string} testPath - Path to check
+ * @returns {boolean} true if file matches safe patterns
+ */
+function isSafeFile(testPath) {
+  if (!testPath) return false;
+  const basename = path.basename(testPath);
+  return SAFE_PATTERNS.some(p => p.test(basename));
+}
+
+/**
+ * Check if path has APPROVED: prefix
+ * @param {string} testPath - Path to check
+ * @returns {boolean} true if path starts with APPROVED:
+ */
+function hasApprovalPrefix(testPath) {
+  return testPath && testPath.startsWith(APPROVED_PREFIX);
+}
+
+/**
+ * Strip APPROVED: prefix from path, warn on suspicious paths
+ * @param {string} testPath - Path to process
+ * @returns {string} Path without APPROVED: prefix
+ */
+function stripApprovalPrefix(testPath) {
+  if (hasApprovalPrefix(testPath)) {
+    const stripped = testPath.slice(APPROVED_PREFIX.length);
+
+    // Warn on suspicious paths (path traversal or absolute)
+    if (stripped.includes('..') || path.isAbsolute(stripped)) {
+      console.error('\x1b[33mWARN:\x1b[0m Approved path is outside project:', stripped);
+    }
+
+    return stripped;
+  }
+  return testPath;
+}
+
+/**
+ * Check if path matches privacy patterns
+ * @param {string} testPath - Path to check
+ * @returns {boolean} true if path matches privacy-sensitive patterns
+ */
+function isPrivacySensitive(testPath) {
+  if (!testPath) return false;
+
+  // Strip prefix for pattern matching
+  const cleanPath = stripApprovalPrefix(testPath);
+  let normalized = cleanPath.replace(/\\/g, '/');
+
+  // Decode URI components to catch obfuscated paths (%2e = '.')
+  try {
+    normalized = decodeURIComponent(normalized);
+  } catch (e) {
+    // Invalid encoding, use as-is
+  }
+
+  // Check safe patterns first - exempt example/sample/template files
+  if (isSafeFile(normalized)) {
+    return false;
+  }
+
+  const basename = path.basename(normalized);
+
+  for (const pattern of PRIVACY_PATTERNS) {
+    if (pattern.test(basename) || pattern.test(normalized)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Extract paths from tool input
+ * @param {Object} toolInput - Tool input object with file_path, path, pattern, or command
+ * @returns {Array<{value: string, field: string}>} Array of extracted paths with field names
+ */
+function extractPaths(toolInput) {
+  const paths = [];
+  if (!toolInput) return paths;
+
+  if (toolInput.file_path) paths.push({ value: toolInput.file_path, field: 'file_path' });
+  if (toolInput.path) paths.push({ value: toolInput.path, field: 'path' });
+  if (toolInput.pattern) paths.push({ value: toolInput.pattern, field: 'pattern' });
+
+  // Check bash commands for file paths
+  if (toolInput.command) {
+    // Look for APPROVED:.env or .env patterns
+    const approvedMatch = toolInput.command.match(/APPROVED:[^\s]+/g) || [];
+    approvedMatch.forEach(p => paths.push({ value: p, field: 'command' }));
+
+    // Only look for .env if no APPROVED: version found
+    if (approvedMatch.length === 0) {
+      const envMatch = toolInput.command.match(/\.env[^\s]*/g) || [];
+      envMatch.forEach(p => paths.push({ value: p, field: 'command' }));
+
+      // Also check bash variable assignments (FILE=.env, ENV_FILE=.env.local)
+      const varAssignments = toolInput.command.match(/\w+=[^\s]*\.env[^\s]*/g) || [];
+      varAssignments.forEach(a => {
+        const value = a.split('=')[1];
+        if (value) paths.push({ value, field: 'command' });
+      });
+
+      // Check command substitution containing sensitive patterns - extract .env from inside
+      const cmdSubst = toolInput.command.match(/\$\([^)]*?(\.env[^\s)]*)[^)]*\)/g) || [];
+      for (const subst of cmdSubst) {
+        const inner = subst.match(/\.env[^\s)]*/);
+        if (inner) paths.push({ value: inner[0], field: 'command' });
+      }
+    }
+  }
+
+  return paths.filter(p => p.value);
+}
+
+/**
+ * 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() {
+  // Check if privacy block is disabled via .cctk.json
+  if (isPrivacyBlockDisabled()) {
+    process.exit(0); // Disabled, allow all
+  }
+
+  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;
+
+  // For Bash commands, only warn but don't block - let Claude Code's permission system handle it
+  // This allows the "Yes → bash cat" flow after AskUserQuestion approval
+  const isBashTool = toolName === 'Bash';
+
+  const paths = extractPaths(toolInput);
+
+  // Check each path
+  for (const { value: testPath } of paths) {
+    if (!isPrivacySensitive(testPath)) continue;
+
+    // Check for approval prefix
+    if (hasApprovalPrefix(testPath)) {
+      // User approved - allow with notice
+      console.error(formatApprovalNotice(testPath));
+      continue; // Check other paths
+    }
+
+    // For Bash: warn but don't block - allows "Yes → bash cat" flow
+    if (isBashTool) {
+      console.error(`\x1b[33mWARN:\x1b[0m Bash command accesses sensitive file: ${testPath}`);
+      continue; // Warn but allow
+    }
+
+    // No approval - block
+    console.error(formatBlockMessage(testPath));
+    process.exit(2); // Block
+  }
+
+  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,
+  };
+}

package/templates/claude/hooks/registry.json

@@ -0,0 +1,77 @@
+{
+  "name": "hooks",
+  "version": "1.0.0",
+  "items": [
+    {
+      "name": "core-libs",
+      "title": "Hook Core Libraries",
+      "description": "Shared utilities required by all hooks",
+      "files": ["hooks/lib/"],
+      "dependencies": {}
+    },
+    {
+      "name": "dev-rules-reminder",
+      "title": "Dev Rules Reminder",
+      "description": "Reminds about development rules during session",
+      "files": ["hooks/dev-rules-reminder.cjs"],
+      "dependencies": {
+        "hooks": ["core-libs"],
+        "workflows": ["development-rules"]
+      }
+    },
+    {
+      "name": "privacy-block",
+      "title": "Privacy Block",
+      "description": "Blocks privacy-sensitive operations",
+      "files": ["hooks/privacy-block.cjs"],
+      "dependencies": {
+        "hooks": ["core-libs"]
+      }
+    },
+    {
+      "name": "scout-block",
+      "title": "Scout Block",
+      "description": "Blocks scout subagent operations",
+      "files": ["hooks/scout-block.cjs", "hooks/scout-block/"],
+      "dependencies": {
+        "hooks": ["core-libs"]
+      }
+    },
+    {
+      "name": "session-end",
+      "title": "Session End",
+      "description": "Cleanup and finalization at session end",
+      "files": ["hooks/session-end.cjs"],
+      "dependencies": {
+        "hooks": ["core-libs"]
+      }
+    },
+    {
+      "name": "session-init",
+      "title": "Session Init",
+      "description": "Bootstrap session with config and context",
+      "files": ["hooks/session-init.cjs"],
+      "dependencies": {
+        "hooks": ["core-libs"]
+      }
+    },
+    {
+      "name": "subagent-init",
+      "title": "Subagent Init",
+      "description": "Initialize subagent context and configuration",
+      "files": ["hooks/subagent-init.cjs"],
+      "dependencies": {
+        "hooks": ["core-libs"]
+      }
+    },
+    {
+      "name": "write-compact-marker",
+      "title": "Write Compact Marker",
+      "description": "Adds compact markers when writing files",
+      "files": ["hooks/write-compact-marker.cjs"],
+      "dependencies": {
+        "hooks": ["core-libs"]
+      }
+    }
+  ]
+}

package/templates/claude/hooks/scout-block/broad-pattern-detector.cjs

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+/**
+ * broad-pattern-detector.cjs - Detect overly broad glob patterns
+ *
+ * Prevents LLMs from filling context by using patterns like "all files"
+ * at project root, which returns ALL files of a type.
+ *
+ * Detection Strategy:
+ * 1. Pattern breadth: recursive glob at start = recursive everywhere
+ * 2. Path depth: Root or shallow paths are high-risk
+ * 3. Combined: Broad pattern + high-level path = BLOCK
+ */
+
+const path = require('node:path');
+
+// Patterns that recursively match everywhere when at root
+// These are dangerous because they return ALL matching files
+const BROAD_PATTERN_REGEXES = [
+  // ** - all files everywhere (no filter at all)
+  /^\*\*$/,
+  // * - all files in root
+  /^\*$/,
+  // **/* - all files everywhere
+  /^\*\*\/\*$/,
+  // **/. - all dotfiles everywhere
+  /^\*\*\/\.\*$/,
+  // **/*.ext - all files with extension (catches .ts, .py, .java, etc.)
+  /^\*\*\/\*\.\w+$/,
+  // **/*.{ext,ext2} - all files with multiple extensions
+  /^\*\*\/\*\.\{[^}]+\}$/,
+  // **/name.ext - all files with specific name anywhere
+  /^\*\*\/[\w-]+\.\w+$/,
+  // *.ext at root (matches all in root, but combined with deep search)
+  /^\*\.\w+$/,
+  // *.{ext,ext2} at root
+  /^\*\.\{[^}]+\}$/,
+];
+
+// Common source directories that indicate a more specific search
+const SPECIFIC_DIRS = [
+  'src',
+  'lib',
+  'app',
+  'apps',
+  'packages',
+  'components',
+  'pages',
+  'api',
+  'server',
+  'client',
+  'web',
+  'mobile',
+  'shared',
+  'common',
+  'utils',
+  'helpers',
+  'services',
+  'hooks',
+  'store',
+  'routes',
+  'models',
+  'controllers',
+  'views',
+  'tests',
+  '__tests__',
+  'spec',
+];
+
+// High-risk paths (project/worktree roots)
+const HIGH_RISK_INDICATORS = [
+  // Worktree paths
+  /\/worktrees\/[^/]+\/?$/,
+  // Project roots (contain package.json, etc.)
+  /^\.?\/?$/,
+  // Shallow paths (just one directory deep)
+  /^[^/]+\/?$/,
+];
+
+/**
+ * Check if a glob pattern is overly broad
+ *
+ * @param {string} pattern - The glob pattern to check
+ * @returns {boolean}
+ */
+function isBroadPattern(pattern) {
+  if (!pattern || typeof pattern !== 'string') return false;
+
+  const normalized = pattern.trim();
+
+  // Check against known broad patterns
+  for (const regex of BROAD_PATTERN_REGEXES) {
+    if (regex.test(normalized)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if pattern contains a specific subdirectory.
+ * Scoped patterns like "src/..." are OK because they target specific dirs.
+ *
+ * @param {string} pattern - The glob pattern
+ * @returns {boolean}
+ */
+function hasSpecificDirectory(pattern) {
+  if (!pattern) return false;
+
+  // Check if pattern starts with a specific directory
+  for (const dir of SPECIFIC_DIRS) {
+    if (pattern.startsWith(`${dir}/`) || pattern.startsWith(`./${dir}/`)) {
+      return true;
+    }
+  }
+
+  // Check for any non-glob directory prefix
+  // e.g., "mydir/..." has a specific directory
+  const firstSegment = pattern.split('/')[0];
+
+  if (firstSegment && !firstSegment.includes('*') && firstSegment !== '.') {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if the base path is at a high-level (risky) location
+ *
+ * @param {string} basePath - The path where glob will run
+ * @param {string} cwd - Current working directory
+ * @returns {boolean}
+ */
+function isHighLevelPath(basePath, cwd) {
+  // No path specified = uses CWD (often project root)
+  if (!basePath) return true;
+
+  const normalized = basePath.replaceAll('\\', '/');
+
+  // Check high-risk indicators
+  for (const regex of HIGH_RISK_INDICATORS) {
+    if (regex.test(normalized)) {
+      return true;
+    }
+  }
+
+  // Check path depth - shallow paths are higher risk
+  const segments = normalized.split('/').filter((s) => s && s !== '.');
+
+  if (segments.length <= 1) {
+    return true;
+  }
+
+  // If path doesn't contain a specific directory, it's high-level
+  const hasSpecific = SPECIFIC_DIRS.some(
+    (dir) =>
+      normalized.includes(`/${dir}/`) ||
+      normalized.includes(`/${dir}`) ||
+      normalized.startsWith(`${dir}/`) ||
+      normalized === dir,
+  );
+
+  return !hasSpecific;
+}
+
+/**
+ * Generate suggestions for more specific patterns
+ *
+ * @param {string} pattern - The broad pattern
+ * @returns {string[]}
+ */
+function suggestSpecificPatterns(pattern) {
+  const suggestions = [];
+
+  // Extract the extension/file part from the pattern
+  let ext = '';
+  const extMatch = pattern.match(/\*\.(\{[^}]+\}|\w+)$/);
+
+  if (extMatch) {
+    ext = extMatch[1];
+  }
+
+  // Suggest common directories
+  const commonDirs = ['src', 'lib', 'app', 'components'];
+
+  for (const dir of commonDirs) {
+    if (ext) {
+      suggestions.push(`${dir}/**/*.${ext}`);
+    } else {
+      suggestions.push(`${dir}/**/*`);
+    }
+  }
+
+  // If it's a TypeScript pattern, add specific suggestions
+  if (pattern.includes('.ts') || pattern.includes('{ts')) {
+    suggestions.unshift('src/**/*.ts', 'src/**/*.tsx');
+  }
+
+  // If it's a JavaScript pattern
+  if (pattern.includes('.js') || pattern.includes('{js')) {
+    suggestions.unshift('src/**/*.js', 'lib/**/*.js');
+  }
+
+  return suggestions.slice(0, 4); // Return top 4 suggestions
+}
+
+/**
+ * Main detection function - check if a Glob tool call is problematic
+ *
+ * @param {Object} toolInput - The tool_input from hook JSON
+ * @param {string} toolInput.pattern - The glob pattern
+ * @param {string} [toolInput.path] - Optional base path
+ * @returns {Object} { blocked: boolean, reason?: string, suggestions?: string[] }
+ */
+function detectBroadPatternIssue(toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') {
+    return { blocked: false };
+  }
+
+  const { pattern, path: basePath } = toolInput;
+
+  // No pattern = nothing to check
+  if (!pattern) {
+    return { blocked: false };
+  }
+
+  // Pattern has a specific directory = OK
+  if (hasSpecificDirectory(pattern)) {
+    return { blocked: false };
+  }
+
+  // Check if pattern is broad
+  if (!isBroadPattern(pattern)) {
+    return { blocked: false };
+  }
+
+  // Check if path is high-level
+  if (!isHighLevelPath(basePath)) {
+    return { blocked: false };
+  }
+
+  // Broad pattern at high-level path = BLOCK
+  return {
+    blocked: true,
+    reason: `Pattern '${pattern}' is too broad for ${basePath || 'project root'}`,
+    pattern,
+    suggestions: suggestSpecificPatterns(pattern),
+  };
+}
+
+/**
+ * Format error message for broad pattern detection
+ *
+ * @param {Object} result - Result from detectBroadPatternIssue
+ * @param {string} claudeDir - Path to .claude directory
+ * @returns {string}
+ */
+function formatBroadPatternError(result, claudeDir) {
+  const { reason, pattern, suggestions } = result;
+
+  const lines = [
+    '',
+    '\u001B[36mNOTE:\u001B[0m This is not an error - this block is intentional to optimize context.',
+    '',
+    '\u001B[31mBLOCKED\u001B[0m: Overly broad glob pattern detected',
+    '',
+    `  \u001B[33mPattern:\u001B[0m  ${pattern}`,
+    `  \u001B[33mReason:\u001B[0m   Would return ALL matching files, filling context`,
+    '',
+    '  \u001B[34mUse more specific patterns:\u001B[0m',
+  ];
+
+  for (const suggestion of suggestions || []) {
+    lines.push(`    • ${suggestion}`);
+  }
+
+  lines.push('', '  \u001B[2mTip: Target specific directories to avoid context overflow\u001B[0m', '');
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  isBroadPattern,
+  hasSpecificDirectory,
+  isHighLevelPath,
+  suggestSpecificPatterns,
+  detectBroadPatternIssue,
+  formatBroadPatternError,
+  BROAD_PATTERN_REGEXES,
+  SPECIFIC_DIRS,
+  HIGH_RISK_INDICATORS,
+};