@macpaw/cctk 1.0.0-beta.1

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

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * scout-block.cjs - Hook for blocking directory access
+ *
+ * Blocks access to directories listed in .claude/.cctkignore
+ * Uses gitignore-spec compliant pattern matching via 'ignore' package
+ *
+ * Blocking Rules:
+ * - File paths: Blocks any file_path/path/pattern containing blocked directories
+ * - Bash commands: Blocks directory access (cd, ls, cat, etc.) but ALLOWS build commands
+ *   - Blocked: cd node_modules, ls packages/web/node_modules, cat dist/file.js
+ *   - Allowed: npm build, go build, cargo build, make, mvn, gradle, docker build, kubectl, terraform
+ *
+ * Configuration:
+ * - Edit .claude/.cctkignore to customize blocked patterns (one per line, # for comments)
+ * - Supports negation patterns (!) to allow specific paths
+ *
+ * Exit Codes:
+ * - 0: Command allowed
+ * - 2: Command blocked
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Import modules
+const { loadPatterns, createMatcher, matchPath } = require('./scout-block/pattern-matcher.cjs');
+const { extractFromToolInput } = require('./scout-block/path-extractor.cjs');
+const { formatBlockedError } = require('./scout-block/error-formatter.cjs');
+const { detectBroadPatternIssue, formatBroadPatternError } = require('./scout-block/broad-pattern-detector.cjs');
+
+// Build command allowlist - these are allowed even if they contain blocked paths
+// Handles flags and filters: npm build, pnpm --filter web run build, yarn workspace app build
+// Also allows: go, cargo, make, mvn/mvnw, gradle/gradlew, dotnet, docker, bazel, cmake, sbt, flutter, swift, ant, ninja, meson
+const BUILD_COMMAND_PATTERN =
+  /^(npm|pnpm|yarn|bun)\s+([^\s]+\s+)*(run\s+)?(build|test|lint|dev|start|install|ci|add|remove|update|publish|pack|init|create|exec)/;
+const TOOL_COMMAND_PATTERN =
+  /^(\.\/)?(npx|pnpx|bunx|tsc|esbuild|vite|webpack|rollup|turbo|nx|jest|vitest|mocha|eslint|prettier|go|cargo|make|mvn|mvnw|gradle|gradlew|dotnet|docker|podman|kubectl|helm|terraform|ansible|bazel|cmake|sbt|flutter|swift|ant|ninja|meson)/;
+
+// Allow execution from .venv/bin/ or venv/bin/ (Unix)
+// Blocks exploration (cat, ls, grep) but allows running venv executables
+const VENV_EXECUTABLE_PATTERN = /(^|[\/\\])\.?venv[\/\\](bin)[\/\\]/;
+
+/**
+ * Check if a command is a build/tooling command (should be allowed)
+ *
+ * @param {string} command - The command to check
+ * @returns {boolean}
+ */
+function isBuildCommand(command) {
+  if (!command || typeof command !== 'string') return false;
+  const trimmed = command.trim();
+
+
+
+return BUILD_COMMAND_PATTERN.test(trimmed) || TOOL_COMMAND_PATTERN.test(trimmed);
+}
+
+/**
+ * Check if command executes from a .venv bin directory
+ * Allows: ~/.claude/skills/.venv/bin/python3 script.py
+ * Allows: .venv/Scripts/python.exe script.py
+ *
+ * @param {string} command - The command to check
+ * @returns {boolean}
+ */
+function isVenvExecutable(command) {
+  if (!command || typeof command !== 'string') return false;
+
+
+return VENV_EXECUTABLE_PATTERN.test(command);
+}
+
+try {
+  // Read stdin synchronously
+  const hookInput = fs.readFileSync(0, 'utf8');
+
+  // Validate input not empty
+  if (!hookInput || hookInput.trim().length === 0) {
+    console.error('ERROR: Empty input');
+    process.exit(2);
+  }
+
+  // Parse JSON
+  let data;
+
+
+  try {
+    data = JSON.parse(hookInput);
+  } catch {
+    // Fail-open for unparseable input
+    console.error('WARN: JSON parse failed, allowing operation');
+    process.exit(0);
+  }
+
+  // Validate structure
+  if (!data.tool_input || typeof data.tool_input !== 'object') {
+    // Fail-open for invalid structure
+    console.error('WARN: Invalid JSON structure, allowing operation');
+    process.exit(0);
+  }
+
+  const toolInput = data.tool_input;
+  const toolName = data.tool_name || 'unknown';
+
+  // Check if it's a build command or venv executable (allowed regardless of paths)
+  if (toolInput.command && (isBuildCommand(toolInput.command) || isVenvExecutable(toolInput.command))) {
+    process.exit(0);
+  }
+
+  // Check for overly broad glob patterns (Glob tool)
+  // This prevents LLMs from filling context with **/*.ts at project root
+  if (toolName === 'Glob' || toolInput.pattern) {
+    const broadResult = detectBroadPatternIssue(toolInput);
+
+
+    if (broadResult.blocked) {
+      const errorMsg = formatBroadPatternError(broadResult, path.dirname(__dirname));
+
+
+      console.error(errorMsg);
+      process.exit(2);
+    }
+  }
+
+  // Load patterns from .cctkignore
+  const scriptDir = __dirname;
+  const claudeDir = path.dirname(scriptDir); // Go up from hooks/ to .claude/
+  const ckignorePath = path.join(claudeDir, '.cctkignore');
+  const patterns = loadPatterns(ckignorePath);
+  const matcher = createMatcher(patterns);
+
+  // Extract paths from tool input
+  const extractedPaths = extractFromToolInput(toolInput);
+
+  // If no paths extracted, allow operation
+  if (extractedPaths.length === 0) {
+    process.exit(0);
+  }
+
+  // Check each path against patterns
+  for (const extractedPath of extractedPaths) {
+    const result = matchPath(matcher, extractedPath);
+
+
+    if (result.blocked) {
+      // Output rich error message
+      const errorMsg = formatBlockedError({
+        path: extractedPath,
+        pattern: result.pattern,
+        tool: toolName,
+        claudeDir
+      });
+
+
+      console.error(errorMsg);
+      process.exit(2);
+    }
+  }
+
+  // All paths allowed
+  process.exit(0);
+} catch (error) {
+  // Fail-open for unexpected errors
+  console.error('WARN: Hook error, allowing operation -', error.message);
+  process.exit(0);
+}

package/templates/claude/hooks/session-end.cjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * SessionEnd Hook - Cleanup on session end
+ *
+ * Fires: When session ends (clear, compact, user exit)
+ * Purpose: Delete compact marker files to reset context baseline on /clear
+ *
+ * Exit Codes:
+ *   0 - Success (non-blocking)
+ */
+
+const fs = require('node:fs');
+const { deleteMarker } = require('./lib/context-tracker.cjs');
+
+async function main() {
+  try {
+    const stdin = fs.readFileSync(0, 'utf8').trim();
+    const data = stdin ? JSON.parse(stdin) : {};
+    const reason = data.reason || 'unknown';
+    const sessionId = data.session_id || null;
+
+    // Delete marker on /clear to reset context baseline
+    // SessionEnd fires with OLD session_id before new session starts
+    // This ensures clean slate for the next session
+    if (reason === 'clear' && sessionId) {
+      deleteMarker(sessionId);
+    }
+
+    process.exit(0);
+  } catch {
+    process.exit(0);
+  }
+}
+
+main();

package/templates/claude/hooks/session-init.cjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * SessionStart Hook - Initializes session environment with project detection
+ *
+ * Fires: Once per session (startup, resume, clear, compact)
+ * Purpose: Load config, detect project info, persist to env vars, output context
+ *
+ * Exit Codes:
+ *   0 - Success (non-blocking, allows continuation)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const {
+  loadConfig,
+  writeEnv,
+  writeSessionState,
+  resolvePlanPath,
+} = require('./lib/cctk-config-utils.cjs');
+const { writeResetMarker } = require('./lib/context-tracker.cjs');
+
+/**
+ * Safely execute shell command with optional timeout
+ * @param {string} cmd - Command to execute
+ * @param {number} timeoutMs - Timeout in milliseconds (default: 5000)
+ */
+function execSafe(cmd, timeoutMs = 5000) {
+  try {
+    return execSync(cmd, {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Detect project type based on workspace indicators
+ */
+function detectProjectType(configOverride) {
+  if (configOverride && configOverride !== 'auto') return configOverride;
+
+  if (fs.existsSync('pnpm-workspace.yaml')) return 'monorepo';
+  if (fs.existsSync('lerna.json')) return 'monorepo';
+
+  if (fs.existsSync('package.json')) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+      if (pkg.workspaces) return 'monorepo';
+      if (pkg.main || pkg.exports) return 'library';
+    } catch (e) { /* ignore */ }
+  }
+
+  return 'single-repo';
+}
+
+/**
+ * Detect package manager from lock files
+ */
+function detectPackageManager(configOverride) {
+  if (configOverride && configOverride !== 'auto') return configOverride;
+
+  if (fs.existsSync('bun.lockb')) return 'bun';
+  if (fs.existsSync('pnpm-lock.yaml')) return 'pnpm';
+  if (fs.existsSync('yarn.lock')) return 'yarn';
+  if (fs.existsSync('package-lock.json')) return 'npm';
+
+  return null;
+}
+
+/**
+ * Get coding level guidelines by reading from output-styles/coding-level.md
+ * Single file approach - users can customize the .md file directly
+ * @param {number} level - Whether coding level guidelines are enabled
+ * @returns {string|null} Guidelines text (frontmatter stripped) or null if disabled
+ */
+function getCodingLevelGuidelines(level) {
+  if (typeof level !== 'number' || level <=0 || level > 3) return null;
+
+  const stylePath = path.join(__dirname, '..', 'output-styles', `coding-level-${level}.md`);
+
+  try {
+    if (!fs.existsSync(stylePath)) return null;
+
+    const content = fs.readFileSync(stylePath, 'utf8');
+    // Strip YAML frontmatter (between --- markers at start of file)
+    const withoutFrontmatter = content.replace(/^---[\s\S]*?---\n*/, '').trim();
+    return withoutFrontmatter;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build context summary for output (compact, single line)
+ * @param {Object} config - Loaded config
+ * @param {Object} detections - Project detections
+ * @param {{ path: string|null, resolvedBy: string|null }} resolved - Plan resolution result
+ * @param {string|null} gitRoot - Git repository root path
+ */
+function buildContextOutput(config, detections, resolved, gitRoot) {
+  const lines = [`Project: ${detections.type || 'unknown'}`];
+  if (detections.pm) lines.push(`PM: ${detections.pm}`);
+  lines.push(`Plan naming: ${config.plan.namingFormat}`);
+
+  // Show git root when different from CWD (subdirectory scenario)
+  if (gitRoot && gitRoot !== process.cwd()) {
+    lines.push(`Root: ${gitRoot}`);
+  }
+
+  // Show plan status with resolution context
+  if (resolved.path) {
+    if (resolved.resolvedBy === 'session') {
+      lines.push(`Plan: ${resolved.path}`);
+    } else {
+      lines.push(`Suggested: ${resolved.path}`);
+    }
+  }
+
+  return lines.join(' | ');
+}
+
+/**
+ * Main hook execution
+ */
+async function main() {
+  try {
+    const stdin = fs.readFileSync(0, 'utf-8').trim();
+    const data = stdin ? JSON.parse(stdin) : {};
+    const envFile = process.env.CLAUDE_ENV_FILE;
+    const source = data.source || 'unknown';
+    const sessionId = data.session_id || null;
+
+    const config = loadConfig();
+
+    // Layer 3: Write reset marker on /clear to signal statusline to reset baseline
+    // This ensures context window percentage resets to 0% on fresh sessions
+    if (source === 'clear' && sessionId) {
+      writeResetMarker(sessionId, 'clear');
+    }
+
+    const detections = {
+      type: detectProjectType(config.project?.type),
+      pm: detectPackageManager(config.project?.packageManager),
+    };
+
+    // Resolve plan - now returns { path, resolvedBy }
+    const resolved = resolvePlanPath(null, config);
+
+    // CRITICAL FIX: Only persist explicitly-set plans to session state
+    // Branch-matched plans are "suggested" - stored separately, not as activePlan
+    // This prevents stale plan pollution on fresh sessions
+    if (sessionId) {
+      writeSessionState(sessionId, {
+        sessionOrigin: process.cwd(),
+        // Only session-resolved plans are truly "active"
+        activePlan: resolved.resolvedBy === 'session' ? resolved.path : null,
+        // Track suggested plan separately (for UI hints, not for report paths)
+        suggestedPlan: resolved.resolvedBy === 'branch' ? resolved.path : null,
+        timestamp: Date.now(),
+        source
+      });
+    }
+
+    // Git context needed for output and subdirectory detection
+    const gitRoot = execSafe('git rev-parse --show-toplevel');
+
+    if (envFile) {
+      writeEnv(envFile, 'CCTK_SESSION_ID', sessionId || '');
+    }
+
+    console.log(`Session ${source}. ${buildContextOutput(config, detections, resolved, gitRoot)}`);
+
+    // Warn user if running from subdirectory (CWD != git root)
+    if (gitRoot && gitRoot !== process.cwd()) {
+      console.log(`⚠️ Running from subdirectory. Plans/docs created at git root: ${gitRoot}`);
+      console.log(`   To avoid this, run Claude from: cd ${gitRoot}`);
+    }
+
+    // Auto-compact can bypass AskUserQuestion approval gates
+    // When context is compacted mid-workflow, the summarization may lose "pending approval" state.
+    // This warning reminds Claude to verify if user approval was pending before proceeding.
+    if (source === 'compact') {
+      console.log(`\n⚠️ CONTEXT COMPACTED - APPROVAL STATE CHECK:`);
+      console.log(`If you were waiting for user approval via AskUserQuestion (e.g., Step 4 review gate),`);
+      console.log(`you MUST re-confirm with the user before proceeding. Do NOT assume approval was given.`);
+      console.log(`Use AskUserQuestion to verify: "Context was compacted. Please confirm approval to continue."`);
+    }
+
+    // Auto-inject coding level guidelines (if enabled)
+    const guidelines = getCodingLevelGuidelines(config.codingLevel)
+
+    if (guidelines) {
+      console.log(`\n${guidelines}`);
+    }
+
+    if (config.assertions?.length > 0) {
+      console.log(`\nUser Assertions:`);
+      config.assertions.forEach((assertion, i) => {
+        console.log(`  ${i + 1}. ${assertion}`);
+      });
+    }
+
+    process.exit(0);
+  } catch (error) {
+    console.error(`SessionStart hook error: ${error.message}`);
+    process.exit(0);
+  }
+}
+
+main();

package/templates/claude/hooks/subagent-init.cjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * SubagentStart Hook - Injects context to subagents (Optimized)
+ *
+ * Fires: When a subagent (Task tool call) is started
+ * Purpose: Inject minimal context using env vars from SessionStart
+ * Target: ~200 tokens (down from ~350)
+ *
+ * Exit Codes:
+ *   0 - Success (non-blocking, allows continuation)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  loadConfig,
+  resolveNamingPattern,
+  getGitBranch,
+  getGitRoot,
+  resolvePlanPath,
+  getReportsPath,
+  normalizePath
+} = require('./lib/cctk-config-utils.cjs');
+
+/**
+ * Get agent-specific context from config
+ */
+function getAgentContext(agentType, config) {
+  const agentConfig = config.subagent?.agents?.[agentType];
+  if (!agentConfig?.contextPrefix) return null;
+  return agentConfig.contextPrefix;
+}
+
+/**
+ * Build trust verification section if enabled
+ */
+function buildTrustVerification(config) {
+  if (!config.trust?.enabled || !config.trust?.passphrase) return [];
+  return [
+    ``,
+    `## Trust Verification`,
+    `Passphrase: "${config.trust.passphrase}"`
+  ];
+}
+
+/**
+ * Main hook execution
+ */
+async function main() {
+  try {
+    const stdin = fs.readFileSync(0, 'utf-8').trim();
+    if (!stdin) process.exit(0);
+
+    const payload = JSON.parse(stdin);
+    const agentType = payload.agent_type || 'unknown';
+    const agentId = payload.agent_id || 'unknown';
+
+    // Load config for trust verification, naming, and agent-specific context
+    const config = loadConfig({ includeProject: false, includeAssertions: false });
+
+    // Use payload.cwd if provided for git operations (monorepo support)
+    // This ensures subagent resolves paths relative to its own CWD, not process.cwd()
+    const effectiveCwd = payload.cwd || process.cwd();
+
+    // Compute naming pattern directly (don't rely on env vars which may not propagate)
+    // Pass effectiveCwd to git commands to support monorepo/submodule scenarios
+    const gitBranch = getGitBranch(effectiveCwd);
+    const gitRoot = getGitRoot(effectiveCwd);
+    const baseDir = gitRoot || effectiveCwd;
+
+    // Debug logging for path resolution troubleshooting
+    if (process.env.CCTK_DEBUG) {
+      console.error(`[subagent-init] effectiveCwd=${effectiveCwd}, gitRoot=${gitRoot}, baseDir=${baseDir}`);
+    }
+    const namePattern = resolveNamingPattern(config.plan, gitBranch);
+
+    const resolved = resolvePlanPath(null, config);
+    const reportsPath = getReportsPath(resolved.path, resolved.resolvedBy, config.plan, config.paths, baseDir);
+    const activePlan = resolved.resolvedBy === 'session' ? resolved.path : '';
+    const suggestedPlan = resolved.resolvedBy === 'branch' ? resolved.path : '';
+    const plansPath = path.join(baseDir, normalizePath(config.paths?.plans) || 'plans');
+    const docsPath = path.join(baseDir, normalizePath(config.paths?.docs) || 'docs');
+    const thinkingLanguage = config.locale?.thinkingLanguage || '';
+    const responseLanguage = config.locale?.responseLanguage || '';
+    // Auto-default thinkingLanguage to 'en' when only responseLanguage is set
+    const effectiveThinking = thinkingLanguage || (responseLanguage ? 'en' : '');
+
+    // Build compact context (~200 tokens)
+    const lines = [];
+
+    // Subagent identification
+    lines.push(`## Subagent: ${agentType}`);
+    lines.push(`ID: ${agentId} | CWD: ${effectiveCwd}`);
+    lines.push(``);
+
+    // Plan context (from env vars)
+    lines.push(`## Context`);
+    if (activePlan) {
+      lines.push(`- Plan: ${activePlan}`);
+    } else if (suggestedPlan) {
+      lines.push(`- Plan: none | Suggested: ${suggestedPlan}`);
+    } else {
+      lines.push(`- Plan: none`);
+    }
+    lines.push(`- Reports: ${reportsPath}`);
+    lines.push(`- Paths: ${plansPath}/ | ${docsPath}/`);
+    lines.push(``);
+
+    // Language (thinking + response, if configured)
+    const hasThinking = effectiveThinking && effectiveThinking !== responseLanguage;
+    if (hasThinking || responseLanguage) {
+      lines.push(`## Language`);
+      if (hasThinking) {
+        lines.push(`- Thinking: Use ${effectiveThinking} for reasoning (logic, precision).`);
+      }
+      if (responseLanguage) {
+        lines.push(`- Response: Respond in ${responseLanguage} (natural, fluent).`);
+      }
+      lines.push(``);
+    }
+
+    // Core rules (minimal)
+    lines.push(`## Rules`);
+    lines.push(`- Reports → ${reportsPath}`);
+    lines.push(`- YAGNI / KISS / DRY`);
+    lines.push(`- Concise, list unresolved Qs at end`);
+
+    // Naming templates (computed directly for reliable injection)
+    lines.push(``);
+    lines.push(`## Naming`);
+    lines.push(`- Report: ${path.join(reportsPath, `${agentType}-${namePattern}.md`)}`);
+    lines.push(`- Plan dir: ${path.join(plansPath, namePattern)}/`);
+
+    // Trust verification (if enabled)
+    lines.push(...buildTrustVerification(config));
+
+    // Agent-specific context (if configured)
+    const agentContext = getAgentContext(agentType, config);
+    if (agentContext) {
+      lines.push(``);
+      lines.push(`## Agent Instructions`);
+      lines.push(agentContext);
+    }
+
+    // CRITICAL: SubagentStart requires hookSpecificOutput.additionalContext format
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SubagentStart",
+        additionalContext: lines.join('\n')
+      }
+    };
+
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  } catch (error) {
+    console.error(`SubagentStart hook error: ${error.message}`);
+    process.exit(0); // Fail-open
+  }
+}
+
+main();