agileflow 2.94.1 → 2.95.0

package/scripts/claude-tmux.sh

@@ -5,28 +5,125 @@
 #   ./claude-tmux.sh              # Start in tmux with default session
 #   ./claude-tmux.sh --no-tmux    # Start without tmux (regular claude)
 #   ./claude-tmux.sh -n           # Same as --no-tmux
+#   ./claude-tmux.sh --rescue     # Kill frozen session and restart fresh
+#   ./claude-tmux.sh --kill       # Kill existing session completely
+#   ./claude-tmux.sh --help       # Show help with keybinds
 #
 # When already in tmux: Just runs claude normally
 # When not in tmux: Creates a tmux session and runs claude inside it
+#
+# FREEZE RECOVERY:
+#   If Claude freezes inside tmux, use these keybinds:
+#   - Alt+k     Send Ctrl+C twice (soft interrupt)
+#   - Alt+K     Force kill the pane immediately
+#   - Alt+R     Respawn pane with fresh shell
+#   - Alt+q     Detach from tmux (session stays alive)
 
 set -e
 
-# Check for --no-tmux flag
+# Parse arguments
 NO_TMUX=false
+RESCUE=false
+KILL_SESSION=false
+SHOW_HELP=false
+
 for arg in "$@"; do
   case $arg in
     --no-tmux|-n)
       NO_TMUX=true
       shift
       ;;
+    --rescue|-r)
+      RESCUE=true
+      shift
+      ;;
+    --kill)
+      KILL_SESSION=true
+      shift
+      ;;
+    --help|-h)
+      SHOW_HELP=true
+      shift
+      ;;
   esac
 done
 
+# Show help
+if [ "$SHOW_HELP" = true ]; then
+  cat << 'EOF'
+AgileFlow Claude tmux Wrapper
+
+USAGE:
+  af [options] [claude-args...]
+  agileflow [options] [claude-args...]
+
+OPTIONS:
+  --no-tmux, -n    Run claude without tmux
+  --rescue, -r     Kill frozen session and restart fresh
+  --kill           Kill existing session completely
+  --help, -h       Show this help
+
+TMUX KEYBINDS:
+  Alt+1-9          Switch to window N
+  Alt+c            Create new window
+  Alt+n/p          Next/previous window
+  Alt+d            Split horizontally
+  Alt+s            Split vertically
+  Alt+arrows       Navigate panes
+  Alt+z            Zoom/unzoom pane
+  Alt+[            Enter copy mode (scroll)
+  Alt+r            Rename window
+  Alt+x            Close pane
+  Alt+w            Close window
+  Alt+q            Detach from tmux
+
+FREEZE RECOVERY:
+  Alt+k            Send Ctrl+C twice (soft interrupt)
+  Alt+K            Force kill pane immediately
+  Alt+R            Respawn pane with fresh shell
+
+If Claude is completely frozen and keybinds don't work:
+  1. Open a new terminal
+  2. Run: af --rescue   (kills and restarts)
+  3. Or:  af --kill     (just kills, doesn't restart)
+EOF
+  exit 0
+fi
+
 # If --no-tmux was specified, just run claude directly
 if [ "$NO_TMUX" = true ]; then
   exec claude "$@"
 fi
 
+# Generate session name based on current directory (needed for rescue/kill)
+DIR_NAME=$(basename "$(pwd)")
+SESSION_NAME="claude-${DIR_NAME}"
+
+# Handle --kill flag
+if [ "$KILL_SESSION" = true ]; then
+  if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+    echo "Killing session: $SESSION_NAME"
+    tmux kill-session -t "$SESSION_NAME"
+    echo "Session killed."
+  else
+    echo "No session named '$SESSION_NAME' found."
+  fi
+  exit 0
+fi
+
+# Handle --rescue flag (kill and restart)
+if [ "$RESCUE" = true ]; then
+  if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+    echo "Killing frozen session: $SESSION_NAME"
+    tmux kill-session -t "$SESSION_NAME"
+    echo "Session killed. Restarting..."
+    sleep 0.5
+  else
+    echo "No existing session to rescue. Starting fresh..."
+  fi
+  # Continue to create new session below
+fi
+
 # Check if tmux auto-spawn is disabled in config
 METADATA_FILE="docs/00-meta/agileflow-metadata.json"
 if [ -f "$METADATA_FILE" ]; then
@@ -62,9 +159,7 @@ if ! command -v tmux &> /dev/null; then
   exec claude "$@"
 fi
 
-# Generate session name based on current directory
-DIR_NAME=$(basename "$(pwd)")
-SESSION_NAME="claude-${DIR_NAME}"
+# SESSION_NAME already generated above (needed for --rescue and --kill)
 
 # Check if session already exists
 if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
@@ -102,7 +197,8 @@ tmux set-option -t "$SESSION_NAME" status 2
 tmux set-option -t "$SESSION_NAME" status-style "bg=#1a1b26,fg=#a9b1d6"
 
 # Line 0 (top): Session name (stripped of claude- prefix) + Keybinds + Git branch
-tmux set-option -t "$SESSION_NAME" status-format[0] "#[bg=#1a1b26]  #[fg=#e8683a bold]#{s/claude-//:session_name}  #[fg=#3b4261]·  #[fg=#7aa2f7]󰘬 #(git branch --show-current 2>/dev/null || echo '-')  #[align=right]#[fg=#7a7e8a]Alt+1-9 tabs  Alt+x close  Alt+q detach  "
+# Shows freeze recovery keys: Alt+k (soft kill), Alt+K (hard kill)
+tmux set-option -t "$SESSION_NAME" status-format[0] "#[bg=#1a1b26]  #[fg=#e8683a bold]#{s/claude-//:session_name}  #[fg=#3b4261]·  #[fg=#7aa2f7]󰘬 #(git branch --show-current 2>/dev/null || echo '-')  #[align=right]#[fg=#7a7e8a]Alt+k freeze  Alt+x close  Alt+q detach  "
 
 # Line 1 (bottom): Window tabs with smart truncation and brand color
 # - Active window: full name (max 15 chars), brand orange highlight
@@ -163,6 +259,16 @@ tmux bind-key -n M-z resize-pane -Z
 # Alt+[ to enter copy mode (for scrolling)
 tmux bind-key -n M-[ copy-mode
 
+# ─── Freeze Recovery Keybindings ─────────────────────────────────────────────
+# Alt+k to send Ctrl+C twice (soft interrupt for frozen processes)
+tmux bind-key -n M-k run-shell "tmux send-keys C-c; sleep 0.5; tmux send-keys C-c"
+
+# Alt+K (shift+k) to force-kill pane immediately (nuclear option for hard freezes)
+tmux bind-key -n M-K kill-pane
+
+# Alt+R (shift+r) to respawn the pane (restart with a fresh shell)
+tmux bind-key -n M-R respawn-pane -k
+
 # Send the claude command to the first window
 CLAUDE_CMD="claude"
 if [ $# -gt 0 ]; then

package/scripts/damage-control/bash-tool-damage-control.js

@@ -1,258 +1,22 @@
 #!/usr/bin/env node
 
 /**
- * bash-tool-damage-control.js - Validate bash commands against security patterns
+ * bash-tool-damage-control.js - PreToolUse hook for Bash tool
  *
- * This PreToolUse hook runs before every Bash tool execution.
- * It checks the command against patterns.yaml to block or ask for
- * confirmation on dangerous commands.
+ * Validates bash commands against patterns in damage-control-patterns.yaml
+ * before execution. Part of AgileFlow's damage control system.
  *
  * Exit codes:
- *   0 = Allow command to proceed (or ask with JSON output)
- *   2 = Block command
+ *   0 - Allow command (or ask via JSON output)
+ *   2 - Block command
  *
- * For ask confirmation, outputs JSON:
- *   {"result": "ask", "message": "Reason for asking"}
+ * For "ask" response, output JSON to stdout:
+ *   { "result": "ask", "message": "Confirm this action?" }
  *
- * Usage (as PreToolUse hook):
- *   node .claude/hooks/damage-control/bash-tool-damage-control.js
- *
- * Environment:
- *   CLAUDE_TOOL_INPUT - JSON string with tool input (contains "command")
- *   CLAUDE_PROJECT_DIR - Project root directory
- */
-
-const fs = require('fs');
-const path = require('path');
-
-// ANSI colors for output
-const c = {
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  red: '\x1b[31m',
-  yellow: '\x1b[33m',
-  cyan: '\x1b[36m',
-};
-
-// Exit codes
-const EXIT_ALLOW = 0;
-const EXIT_BLOCK = 2;
-
-/**
- * Load patterns from YAML file
- * Falls back to built-in patterns if YAML parsing fails
- */
-function loadPatterns(projectDir) {
-  const locations = [
-    path.join(projectDir, '.claude/hooks/damage-control/patterns.yaml'),
-    path.join(projectDir, '.agileflow/hooks/damage-control/patterns.yaml'),
-    path.join(projectDir, 'patterns.yaml'),
-  ];
-
-  for (const loc of locations) {
-    if (fs.existsSync(loc)) {
-      try {
-        const content = fs.readFileSync(loc, 'utf8');
-        // Simple YAML parsing for our specific structure
-        return parseSimpleYaml(content);
-      } catch (e) {
-        console.error(`Warning: Could not parse ${loc}: ${e.message}`);
-      }
-    }
-  }
-
-  // Return built-in defaults if no file found
-  return getDefaultPatterns();
-}
-
-/**
- * Simple YAML parser for patterns.yaml structure
- * Only handles the specific structure we use (arrays of objects with pattern/reason/ask)
- */
-function parseSimpleYaml(content) {
-  const patterns = {
-    bashToolPatterns: [],
-    askPatterns: [],
-    agileflowPatterns: [],
-  };
-
-  let currentSection = null;
-  let currentItem = null;
-
-  const lines = content.split('\n');
-
-  for (const line of lines) {
-    // Skip comments and empty lines
-    if (line.trim().startsWith('#') || line.trim() === '') continue;
-
-    // Check for section headers
-    if (line.match(/^bashToolPatterns:/)) {
-      currentSection = 'bashToolPatterns';
-      continue;
-    }
-    if (line.match(/^askPatterns:/)) {
-      currentSection = 'askPatterns';
-      continue;
-    }
-    if (line.match(/^agileflowPatterns:/)) {
-      currentSection = 'agileflowPatterns';
-      continue;
-    }
-    if (line.match(/^(zeroAccessPaths|readOnlyPaths|noDeletePaths|config):/)) {
-      currentSection = null; // Skip non-pattern sections
-      continue;
-    }
-
-    // Parse pattern items
-    if (currentSection && patterns[currentSection]) {
-      const patternMatch = line.match(/^\s+-\s*pattern:\s*['"]?(.+?)['"]?\s*$/);
-      if (patternMatch) {
-        currentItem = { pattern: patternMatch[1] };
-        patterns[currentSection].push(currentItem);
-        continue;
-      }
-
-      const reasonMatch = line.match(/^\s+reason:\s*['"]?(.+?)['"]?\s*$/);
-      if (reasonMatch && currentItem) {
-        currentItem.reason = reasonMatch[1];
-        continue;
-      }
-
-      const askMatch = line.match(/^\s+ask:\s*(true|false)\s*$/);
-      if (askMatch && currentItem) {
-        currentItem.ask = askMatch[1] === 'true';
-        continue;
-      }
-    }
-  }
-
-  return patterns;
-}
-
-/**
- * Built-in default patterns (used if patterns.yaml not found)
- */
-function getDefaultPatterns() {
-  return {
-    bashToolPatterns: [
-      { pattern: '\\brm\\s+-[rRf]', reason: 'rm with recursive or force flags' },
-      { pattern: 'DROP\\s+(TABLE|DATABASE)', reason: 'DROP commands are destructive' },
-      { pattern: 'DELETE\\s+FROM\\s+\\w+\\s*;', reason: 'DELETE without WHERE clause' },
-      { pattern: 'TRUNCATE\\s+(TABLE\\s+)?\\w+', reason: 'TRUNCATE removes all data' },
-      {
-        pattern: 'git\\s+push\\s+.*--force',
-        reason: 'Force push can overwrite history',
-        ask: true,
-      },
-      { pattern: 'git\\s+reset\\s+--hard', reason: 'Hard reset discards changes', ask: true },
-    ],
-    askPatterns: [
-      { pattern: 'DELETE\\s+FROM\\s+\\w+\\s+WHERE', reason: 'Confirm record deletion' },
-      { pattern: 'npm\\s+publish', reason: 'Publishing to npm is permanent' },
-    ],
-    agileflowPatterns: [
-      { pattern: 'rm.*\\.agileflow', reason: 'Deleting .agileflow breaks installation' },
-      { pattern: 'rm.*\\.claude', reason: 'Deleting .claude breaks configuration' },
-    ],
-  };
-}
-
-/**
- * Check command against patterns
- * Returns: { blocked: boolean, ask: boolean, reason: string }
- */
-function checkCommand(command, patterns) {
-  // Combine all pattern sources
-  const allPatterns = [...(patterns.bashToolPatterns || []), ...(patterns.agileflowPatterns || [])];
-
-  // Check block/ask patterns
-  for (const p of allPatterns) {
-    try {
-      const regex = new RegExp(p.pattern, 'i');
-      if (regex.test(command)) {
-        if (p.ask) {
-          return { blocked: false, ask: true, reason: p.reason };
-        }
-        return { blocked: true, ask: false, reason: p.reason };
-      }
-    } catch (e) {
-      // Invalid regex, skip
-      console.error(`Warning: Invalid regex pattern: ${p.pattern}`);
-    }
-  }
-
-  // Check ask-only patterns
-  for (const p of patterns.askPatterns || []) {
-    try {
-      const regex = new RegExp(p.pattern, 'i');
-      if (regex.test(command)) {
-        return { blocked: false, ask: true, reason: p.reason };
-      }
-    } catch (e) {
-      // Invalid regex, skip
-    }
-  }
-
-  return { blocked: false, ask: false, reason: null };
-}
-
-/**
- * Main entry point
+ * Usage: Configured as PreToolUse hook in .claude/settings.json
  */
-function main() {
-  // Get tool input from environment
-  const toolInput = process.env.CLAUDE_TOOL_INPUT;
-  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-
-  if (!toolInput) {
-    // No input, allow by default
-    process.exit(EXIT_ALLOW);
-  }
-
-  let input;
-  try {
-    input = JSON.parse(toolInput);
-  } catch (e) {
-    console.error('Error parsing CLAUDE_TOOL_INPUT:', e.message);
-    process.exit(EXIT_ALLOW);
-  }
-
-  const command = input.command;
-  if (!command) {
-    process.exit(EXIT_ALLOW);
-  }
-
-  // Load patterns
-  const patterns = loadPatterns(projectDir);
-
-  // Check command
-  const result = checkCommand(command, patterns);
-
-  if (result.blocked) {
-    // Block the command
-    console.error(`${c.red}${c.bold}BLOCKED${c.reset}: ${result.reason}`);
-    console.error(`${c.yellow}Command: ${command}${c.reset}`);
-    console.error(`${c.cyan}This command was blocked by damage control.${c.reset}`);
-    process.exit(EXIT_BLOCK);
-  }
-
-  if (result.ask) {
-    // Ask for confirmation
-    const response = {
-      result: 'ask',
-      message: `${result.reason}\n\nCommand: ${command}\n\nProceed with this command?`,
-    };
-    console.log(JSON.stringify(response));
-    process.exit(EXIT_ALLOW);
-  }
-
-  // Allow the command
-  process.exit(EXIT_ALLOW);
-}
 
-// Run if called directly
-if (require.main === module) {
-  main();
-}
+const { createBashHook } = require('../lib/damage-control-utils');
 
-module.exports = { checkCommand, loadPatterns, parseSimpleYaml };
+// Run the hook using factory
+createBashHook()();

package/scripts/damage-control/edit-tool-damage-control.js

@@ -1,259 +1,19 @@
 #!/usr/bin/env node
 
 /**
- * edit-tool-damage-control.js - Enforce path protection for Edit tool
+ * edit-tool-damage-control.js - PreToolUse hook for Edit tool
  *
- * This PreToolUse hook runs before every Edit tool execution.
- * It checks the file path against patterns.yaml to block edits
- * to protected paths.
- *
- * Path protection levels:
- *   zeroAccessPaths: Cannot read, write, edit, or delete
- *   readOnlyPaths: Can read, cannot modify or delete
- *   noDeletePaths: Can read and modify, cannot delete (Edit is allowed)
+ * Validates file paths against access control patterns in damage-control-patterns.yaml
+ * before allowing file edits. Part of AgileFlow's damage control system.
  *
  * Exit codes:
- *   0 = Allow edit to proceed
- *   2 = Block edit
- *
- * Usage (as PreToolUse hook):
- *   node .claude/hooks/damage-control/edit-tool-damage-control.js
+ *   0 - Allow operation
+ *   2 - Block operation
  *
- * Environment:
- *   CLAUDE_TOOL_INPUT - JSON string with tool input (contains "file_path")
- *   CLAUDE_PROJECT_DIR - Project root directory
- */
-
-const fs = require('fs');
-const path = require('path');
-
-// ANSI colors for output
-const c = {
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  red: '\x1b[31m',
-  yellow: '\x1b[33m',
-  cyan: '\x1b[36m',
-};
-
-// Exit codes
-const EXIT_ALLOW = 0;
-const EXIT_BLOCK = 2;
-
-/**
- * Load path protection rules from patterns.yaml
- */
-function loadPathRules(projectDir) {
-  const locations = [
-    path.join(projectDir, '.claude/hooks/damage-control/patterns.yaml'),
-    path.join(projectDir, '.agileflow/hooks/damage-control/patterns.yaml'),
-    path.join(projectDir, 'patterns.yaml'),
-  ];
-
-  for (const loc of locations) {
-    if (fs.existsSync(loc)) {
-      try {
-        const content = fs.readFileSync(loc, 'utf8');
-        return parsePathRules(content);
-      } catch (e) {
-        console.error(`Warning: Could not parse ${loc}: ${e.message}`);
-      }
-    }
-  }
-
-  return getDefaultPathRules();
-}
-
-/**
- * Parse path rules from YAML content
+ * Usage: Configured as PreToolUse hook in .claude/settings.json
  */
-function parsePathRules(content) {
-  const rules = {
-    zeroAccessPaths: [],
-    readOnlyPaths: [],
-    noDeletePaths: [],
-  };
-
-  let currentSection = null;
-
-  const lines = content.split('\n');
-
-  for (const line of lines) {
-    if (line.trim().startsWith('#') || line.trim() === '') continue;
-
-    if (line.match(/^zeroAccessPaths:/)) {
-      currentSection = 'zeroAccessPaths';
-      continue;
-    }
-    if (line.match(/^readOnlyPaths:/)) {
-      currentSection = 'readOnlyPaths';
-      continue;
-    }
-    if (line.match(/^noDeletePaths:/)) {
-      currentSection = 'noDeletePaths';
-      continue;
-    }
-    if (line.match(/^(bashToolPatterns|askPatterns|agileflowPatterns|config):/)) {
-      currentSection = null;
-      continue;
-    }
-
-    if (currentSection && rules[currentSection]) {
-      const pathMatch = line.match(/^\s+-\s*['"]?(.+?)['"]?\s*$/);
-      if (pathMatch) {
-        rules[currentSection].push(pathMatch[1]);
-      }
-    }
-  }
-
-  return rules;
-}
-
-/**
- * Default path rules if patterns.yaml not found
- */
-function getDefaultPathRules() {
-  return {
-    zeroAccessPaths: ['~/.ssh/', '~/.aws/credentials', '.env', '.env.local', '.env.production'],
-    readOnlyPaths: ['/etc/', '~/.bashrc', '~/.zshrc', 'package-lock.json', 'yarn.lock', '.git/'],
-    noDeletePaths: ['.agileflow/', '.claude/', 'docs/09-agents/status.json', 'CLAUDE.md'],
-  };
-}
-
-/**
- * Expand home directory in path
- */
-function expandHome(filePath) {
-  if (filePath.startsWith('~/')) {
-    return path.join(process.env.HOME || '', filePath.slice(2));
-  }
-  return filePath;
-}
-
-/**
- * Check if a file path matches a pattern
- * Supports:
- *   - Exact paths
- *   - Directory prefixes (ending with /)
- *   - Glob wildcards (**)
- */
-function pathMatches(filePath, pattern) {
-  const expandedPattern = expandHome(pattern);
-  const normalizedFile = path.normalize(filePath);
-  const normalizedPattern = path.normalize(expandedPattern);
-
-  // Exact match
-  if (normalizedFile === normalizedPattern) return true;
-
-  // Directory prefix match (pattern ends with /)
-  if (pattern.endsWith('/')) {
-    if (normalizedFile.startsWith(normalizedPattern)) return true;
-  }
-
-  // Glob pattern (**/)
-  if (pattern.includes('**/')) {
-    const globPart = pattern.split('**/')[1];
-    if (normalizedFile.includes(globPart)) return true;
-  }
-
-  // Simple wildcard at end
-  if (pattern.endsWith('*')) {
-    const prefix = normalizedPattern.slice(0, -1);
-    if (normalizedFile.startsWith(prefix)) return true;
-  }
-
-  // Basename match (for patterns like .env)
-  if (!pattern.includes('/') && !pattern.includes(path.sep)) {
-    const basename = path.basename(normalizedFile);
-    if (basename === pattern) return true;
-    // Pattern like .env* matching .env.local
-    if (pattern.endsWith('*')) {
-      const patternBase = pattern.slice(0, -1);
-      if (basename.startsWith(patternBase)) return true;
-    }
-  }
-
-  return false;
-}
-
-/**
- * Check if file path is protected
- * Returns: { blocked: boolean, reason: string, level: string }
- */
-function checkPath(filePath, rules) {
-  // Check zero access paths (blocked completely)
-  for (const pattern of rules.zeroAccessPaths) {
-    if (pathMatches(filePath, pattern)) {
-      return {
-        blocked: true,
-        reason: `Path is in zero-access protected list: ${pattern}`,
-        level: 'zero-access',
-      };
-    }
-  }
-
-  // Check read-only paths (cannot edit)
-  for (const pattern of rules.readOnlyPaths) {
-    if (pathMatches(filePath, pattern)) {
-      return {
-        blocked: true,
-        reason: `Path is read-only: ${pattern}`,
-        level: 'read-only',
-      };
-    }
-  }
-
-  // noDeletePaths allows editing, so we don't block here
-  // (deletion is handled by a different mechanism or file watcher)
-
-  return { blocked: false, reason: null, level: null };
-}
-
-/**
- * Main entry point
- */
-function main() {
-  const toolInput = process.env.CLAUDE_TOOL_INPUT;
-  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-
-  if (!toolInput) {
-    process.exit(EXIT_ALLOW);
-  }
-
-  let input;
-  try {
-    input = JSON.parse(toolInput);
-  } catch (e) {
-    console.error('Error parsing CLAUDE_TOOL_INPUT:', e.message);
-    process.exit(EXIT_ALLOW);
-  }
-
-  const filePath = input.file_path;
-  if (!filePath) {
-    process.exit(EXIT_ALLOW);
-  }
-
-  // Resolve to absolute path
-  const absolutePath = path.isAbsolute(filePath) ? filePath : path.join(projectDir, filePath);
-
-  // Load rules
-  const rules = loadPathRules(projectDir);
-
-  // Check path
-  const result = checkPath(absolutePath, rules);
-
-  if (result.blocked) {
-    console.error(`${c.red}${c.bold}BLOCKED${c.reset}: ${result.reason}`);
-    console.error(`${c.yellow}File: ${filePath}${c.reset}`);
-    console.error(`${c.cyan}This file is protected by damage control (${result.level}).${c.reset}`);
-    process.exit(EXIT_BLOCK);
-  }
-
-  process.exit(EXIT_ALLOW);
-}
 
-if (require.main === module) {
-  main();
-}
+const { createPathHook } = require('../lib/damage-control-utils');
 
-module.exports = { checkPath, loadPathRules, pathMatches };
+// Run the hook using factory
+createPathHook('edit')();