claude-git-hooks 2.6.3 → 2.8.0

package/lib/utils/claude-client.js

@@ -21,7 +21,7 @@ import path from 'path';
 import os from 'os';
 import logger from './logger.js';
 import config from '../config.js';
-import { detectClaudeError, formatClaudeError, ClaudeErrorType } from './claude-diagnostics.js';
+import { detectClaudeError, formatClaudeError, ClaudeErrorType, isRecoverableError } from './claude-diagnostics.js';
 import { which } from './which-command.js';
 
 /**
@@ -103,12 +103,15 @@ const getClaudeCommand = () => {
         if (wslPath) {
             try {
                 // Verify Claude exists in WSL
-                execSync(`"${wslPath}" claude --version`, { stdio: 'ignore', timeout: 5000 });
+                // Increased timeout from 5s to 15s to handle system load better
+                const wslCheckTimeout = config.system.wslCheckTimeout || 15000;
+                execSync(`"${wslPath}" claude --version`, { stdio: 'ignore', timeout: wslCheckTimeout });
                 logger.debug('claude-client - getClaudeCommand', 'Using WSL Claude CLI', { wslPath });
                 return { command: wslPath, args: ['claude'] };
             } catch (wslError) {
                 // Differentiate error types for accurate user feedback
                 const errorMsg = wslError.message || '';
+                const wslCheckTimeout = config.system.wslCheckTimeout || 15000;
 
                 // Timeout: Transient system load issue
                 if (errorMsg.includes('ETIMEDOUT')) {
@@ -117,6 +120,7 @@ const getClaudeCommand = () => {
                             platform: 'Windows',
                             wslPath,
                             error: 'ETIMEDOUT',
+                            timeoutValue: wslCheckTimeout,
                             suggestion: 'System is busy. Wait a moment and try again, or skip analysis: git commit --no-verify'
                         }
                     });
@@ -241,13 +245,57 @@ const executeClaude = (prompt, { timeout = 120000, allowedTools = [] } = {}) =>
 
     // Handle process completion
     claude.on('close', (code) => {
-        const duration = Date.now() - startTime;
+        const elapsedTime = Date.now() - startTime;
+
+        // Check for "Execution error" even when exit code is 0
+        // Why: Claude CLI sometimes returns "Execution error" with exit code 0
+        // This occurs during API rate limiting or temporary backend issues
+        // IMPORTANT: Only check for EXACT match to avoid false positives
+        if (stdout.trim() === 'Execution error') {
+            const errorInfo = detectClaudeError(stdout, stderr, code);
+
+            logger.error(
+                'claude-client - executeClaude',
+                `Claude CLI returned execution error (exit ${code})`,
+                new ClaudeClientError(`Claude CLI error: ${errorInfo.type}`, {
+                    output: { stdout, stderr },
+                    context: {
+                        exitCode: code,
+                        elapsedTime,
+                        timeoutValue: timeout,
+                        errorType: errorInfo.type
+                    }
+                })
+            );
+
+            // Merge timing info into errorInfo for formatting
+            const errorInfoWithTiming = {
+                ...errorInfo,
+                elapsedTime,
+                timeoutValue: timeout
+            };
+
+            // Show formatted error to user
+            const formattedError = formatClaudeError(errorInfoWithTiming);
+            console.error(`\n${  formattedError  }\n`);
+
+            reject(new ClaudeClientError(`Claude CLI error: ${errorInfo.type}`, {
+                output: { stdout, stderr },
+                context: {
+                    exitCode: code,
+                    elapsedTime,
+                    timeoutValue: timeout,
+                    errorInfo
+                }
+            }));
+            return;
+        }
 
         if (code === 0) {
             logger.debug(
                 'claude-client - executeClaude',
                 'Claude CLI execution successful',
-                { duration, outputLength: stdout.length }
+                { elapsedTime, outputLength: stdout.length }
             );
             resolve(stdout);
         } else {
@@ -259,23 +307,42 @@ const executeClaude = (prompt, { timeout = 120000, allowedTools = [] } = {}) =>
                 `Claude CLI failed: ${errorInfo.type}`,
                 new ClaudeClientError(`Claude CLI error: ${errorInfo.type}`, {
                     output: { stdout, stderr },
-                    context: { exitCode: code, duration, errorType: errorInfo.type }
+                    context: {
+                        exitCode: code,
+                        elapsedTime,
+                        timeoutValue: timeout,
+                        errorType: errorInfo.type
+                    }
                 })
             );
 
+            // Merge timing info into errorInfo for formatting
+            const errorInfoWithTiming = {
+                ...errorInfo,
+                elapsedTime,
+                timeoutValue: timeout
+            };
+
             // Show formatted error to user
-            const formattedError = formatClaudeError(errorInfo);
+            const formattedError = formatClaudeError(errorInfoWithTiming);
             console.error(`\n${  formattedError  }\n`);
 
             reject(new ClaudeClientError(`Claude CLI error: ${errorInfo.type}`, {
                 output: { stdout, stderr },
-                context: { exitCode: code, duration, errorInfo }
+                context: {
+                    exitCode: code,
+                    elapsedTime,
+                    timeoutValue: timeout,
+                    errorInfo
+                }
             }));
         }
     });
 
     // Handle errors
     claude.on('error', (error) => {
+        const elapsedTime = Date.now() - startTime;
+
         logger.error(
             'claude-client - executeClaude',
             'Failed to spawn Claude CLI process',
@@ -284,23 +351,36 @@ const executeClaude = (prompt, { timeout = 120000, allowedTools = [] } = {}) =>
 
         reject(new ClaudeClientError('Failed to spawn Claude CLI', {
             cause: error,
-            context: { command, args }
+            context: {
+                command,
+                args,
+                elapsedTime,
+                timeoutValue: timeout
+            }
         }));
     });
 
     // Set up timeout
     const timeoutId = setTimeout(() => {
+        const elapsedTime = Date.now() - startTime;
         claude.kill();
+
         logger.error(
             'claude-client - executeClaude',
             'Claude CLI execution timed out',
             new ClaudeClientError('Claude CLI timeout', {
-                context: { timeout }
+                context: {
+                    elapsedTime,
+                    timeoutValue: timeout
+                }
             })
         );
 
         reject(new ClaudeClientError('Claude CLI execution timed out', {
-            context: { timeout }
+            context: {
+                elapsedTime,
+                timeoutValue: timeout
+            }
         }));
     }, timeout);
 
@@ -580,6 +660,90 @@ const saveDebugResponse = async (prompt, response, filename = config.output.debu
     }
 };
 
+/**
+ * Wraps an async function with retry logic for recoverable errors
+ * Why: Reusable retry logic for Claude CLI operations
+ *
+ * @param {Function} fn - Async function to execute with retry
+ * @param {Object} options - Retry options
+ * @param {number} options.maxRetries - Maximum retry attempts (default: 3)
+ * @param {number} options.baseRetryDelay - Base delay in ms (default: 2000)
+ * @param {number} options.retryCount - Current retry attempt (internal, default: 0)
+ * @param {string} options.operationName - Name for logging (default: 'operation')
+ * @returns {Promise<any>} Result from fn
+ * @throws {Error} If fn fails after all retries
+ */
+const withRetry = async (fn, { maxRetries = 3, baseRetryDelay = 2000, retryCount = 0, operationName = 'operation' } = {}) => {
+    const retryDelay = baseRetryDelay * Math.pow(2, retryCount);
+
+    try {
+        return await fn();
+    } catch (error) {
+        // Check if error is recoverable and we haven't exceeded retry limit
+        const hasContext = !!error.context;
+        const hasErrorInfo = !!error.context?.errorInfo;
+        const isRecoverable = hasErrorInfo ? isRecoverableError(error.context.errorInfo) : false;
+        const canRetry = retryCount < maxRetries;
+
+        logger.debug(
+            'claude-client - withRetry',
+            `Retry check for ${operationName}`,
+            {
+                retryCount,
+                maxRetries,
+                hasContext,
+                hasErrorInfo,
+                isRecoverable,
+                canRetry,
+                errorType: error.context?.errorInfo?.type,
+                errorName: error.name
+            }
+        );
+
+        const shouldRetry = canRetry && hasContext && hasErrorInfo && isRecoverable;
+
+        if (shouldRetry) {
+            logger.debug(
+                'claude-client - withRetry',
+                `Recoverable error detected, retrying ${operationName} in ${retryDelay}ms (attempt ${retryCount + 1}/${maxRetries})`,
+                { errorType: error.context.errorInfo.type }
+            );
+
+            console.log(`\n⏳ Retrying in ${retryDelay / 1000} seconds due to ${error.context.errorInfo.type}...\n`);
+
+            // Wait before retry
+            await new Promise(resolve => setTimeout(resolve, retryDelay));
+
+            // Retry with incremented count
+            return withRetry(fn, { maxRetries, baseRetryDelay, retryCount: retryCount + 1, operationName });
+        }
+
+        // Add retry attempt to error context if not already present
+        if (error.context && !error.context.retryAttempt) {
+            error.context.retryAttempt = retryCount;
+            error.context.maxRetries = maxRetries;
+        }
+
+        logger.error('claude-client - withRetry', `${operationName} failed after retries`, error);
+        throw error;
+    }
+};
+
+/**
+ * Executes Claude CLI with retry logic
+ * Why: Provides retry capability for executeClaude calls
+ *
+ * @param {string} prompt - Prompt text
+ * @param {Object} options - Execution options (timeout, allowedTools)
+ * @returns {Promise<string>} Claude's response
+ */
+const executeClaudeWithRetry = async (prompt, options = {}) => {
+    return withRetry(
+        () => executeClaude(prompt, options),
+        { operationName: 'executeClaude' }
+    );
+};
+
 /**
  * Analyzes code using Claude CLI
  * Why: High-level interface that handles execution, parsing, and debug
@@ -598,34 +762,34 @@ const analyzeCode = async (prompt, { timeout = 120000, saveDebug = config.system
         { promptLength: prompt.length, timeout, saveDebug }
     );
 
-    try {
-        // Execute Claude CLI
-        const response = await executeClaude(prompt, { timeout });
-
-        // Save debug if requested
-        if (saveDebug) {
-            await saveDebugResponse(prompt, response);
-        }
+    // Use withRetry to wrap the entire analysis flow
+    return withRetry(
+        async () => {
+            // Execute Claude CLI
+            const response = await executeClaude(prompt, { timeout });
 
-        // Extract and parse JSON
-        const result = extractJSON(response);
-
-        logger.debug(
-            'claude-client - analyzeCode',
-            'Analysis complete',
-            {
-                hasApproved: 'approved' in result,
-                hasQualityGate: 'QUALITY_GATE' in result,
-                blockingIssuesCount: result.blockingIssues?.length ?? 0
+            // Save debug if requested
+            if (saveDebug) {
+                await saveDebugResponse(prompt, response);
             }
-        );
 
-        return result;
+            // Extract and parse JSON
+            const result = extractJSON(response);
 
-    } catch (error) {
-        logger.error('claude-client - analyzeCode', 'Code analysis failed', error);
-        throw error;
-    }
+            logger.debug(
+                'claude-client - analyzeCode',
+                'Analysis complete',
+                {
+                    hasApproved: 'approved' in result,
+                    hasQualityGate: 'QUALITY_GATE' in result,
+                    blockingIssuesCount: result.blockingIssues?.length ?? 0
+                }
+            );
+
+            return result;
+        },
+        { operationName: 'analyzeCode' }
+    );
 };
 
 /**
@@ -679,6 +843,7 @@ const analyzeCodeParallel = async (prompts, options = {}) => {
 export {
     ClaudeClientError,
     executeClaude,
+    executeClaudeWithRetry,
     executeClaudeInteractive,
     extractJSON,
     saveDebugResponse,

package/lib/utils/claude-diagnostics.js

@@ -25,6 +25,7 @@ export const ClaudeErrorType = {
     TIMEOUT: 'TIMEOUT',
     NETWORK: 'NETWORK',
     INVALID_RESPONSE: 'INVALID_RESPONSE',
+    EXECUTION_ERROR: 'EXECUTION_ERROR',
     GENERIC: 'GENERIC'
 };
 
@@ -44,7 +45,20 @@ export const ClaudeErrorType = {
  * @returns {Object|null} Error information or null if no specific error detected
  */
 export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
-    // 1. Rate limit detection
+    // 1. Execution error detection (Claude CLI internal error)
+    // This occurs when Claude API returns an error instead of valid response
+    // Often caused by rate limiting, API errors, or temporary backend issues
+    // IMPORTANT: Only match EXACT "Execution error" response, not partial matches
+    const trimmedStdout = stdout.trim();
+    if (trimmedStdout === 'Execution error') {
+        return {
+            type: ClaudeErrorType.EXECUTION_ERROR,
+            exitCode,
+            stdout: stdout.substring(0, 100)
+        };
+    }
+
+    // 2. Rate limit detection
     const rateLimitMatch = stdout.match(/Claude AI usage limit reached\|(\d+)/);
     if (rateLimitMatch) {
         const resetTimestamp = parseInt(rateLimitMatch[1], 10);
@@ -61,7 +75,7 @@ export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
         };
     }
 
-    // 2. Authentication failure detection
+    // 3. Authentication failure detection
     if (stdout.includes('not authenticated') || stderr.includes('not authenticated') ||
         stdout.includes('authentication failed') || stderr.includes('authentication failed')) {
         return {
@@ -70,7 +84,7 @@ export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
         };
     }
 
-    // 3. Network errors
+    // 4. Network errors
     if (stderr.includes('ENOTFOUND') || stderr.includes('ECONNREFUSED') ||
         stderr.includes('network error') || stderr.includes('connection refused')) {
         return {
@@ -79,7 +93,7 @@ export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
         };
     }
 
-    // 4. Invalid response (JSON parsing errors)
+    // 5. Invalid response (JSON parsing errors)
     if (stdout.includes('SyntaxError') || stdout.includes('Unexpected token')) {
         return {
             type: ClaudeErrorType.INVALID_RESPONSE,
@@ -87,7 +101,7 @@ export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
         };
     }
 
-    // 5. Generic error
+    // 6. Generic error
     return {
         type: ClaudeErrorType.GENERIC,
         exitCode,
@@ -96,6 +110,38 @@ export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
     };
 };
 
+/**
+ * Formats timing information for error messages
+ * @param {Object} errorInfo - Error information with optional timing data
+ * @returns {Array<string>} Array of formatted timing lines
+ */
+const formatTimingInfo = (errorInfo) => {
+    const lines = [];
+    const { elapsedTime, timeoutValue, retryAttempt, maxRetries } = errorInfo;
+
+    if (elapsedTime !== undefined || timeoutValue !== undefined || retryAttempt !== undefined) {
+        lines.push('');
+        lines.push('Timing information:');
+
+        if (elapsedTime !== undefined) {
+            const seconds = (elapsedTime / 1000).toFixed(2);
+            lines.push(`  Elapsed time: ${seconds}s`);
+        }
+
+        if (timeoutValue !== undefined) {
+            const timeoutSeconds = (timeoutValue / 1000).toFixed(0);
+            lines.push(`  Timeout limit: ${timeoutSeconds}s`);
+        }
+
+        if (retryAttempt !== undefined) {
+            const maxRetriesText = maxRetries !== undefined ? `/${maxRetries}` : '';
+            lines.push(`  Retry attempt: ${retryAttempt}${maxRetriesText}`);
+        }
+    }
+
+    return lines;
+};
+
 /**
  * Formats Claude error message with diagnostics and remediation steps
  * Why: Provides consistent, actionable error messages
@@ -107,6 +153,9 @@ export const formatClaudeError = (errorInfo) => {
     const lines = [];
 
     switch (errorInfo.type) {
+        case ClaudeErrorType.EXECUTION_ERROR:
+            return formatExecutionError(errorInfo);
+
         case ClaudeErrorType.RATE_LIMIT:
             return formatRateLimitError(errorInfo);
 
@@ -125,10 +174,42 @@ export const formatClaudeError = (errorInfo) => {
     }
 };
 
+/**
+ * Format execution error
+ */
+const formatExecutionError = (errorInfo) => {
+    const { exitCode, stdout } = errorInfo;
+    const lines = [];
+
+    lines.push('❌ Claude CLI execution error');
+    lines.push('');
+    lines.push('Claude returned "Execution error" instead of valid response.');
+    lines.push(...formatTimingInfo(errorInfo));
+    lines.push('');
+    lines.push('Common causes:');
+    lines.push('  1. API rate limiting (burst limits)');
+    lines.push('  2. Temporary Claude API backend issues');
+    lines.push('  3. Request/response size limits exceeded');
+    lines.push('');
+    lines.push('Solutions:');
+    lines.push('  1. Wait 10-30 seconds and try again');
+    lines.push('  2. Reduce prompt size by committing fewer files at once');
+    lines.push('  3. Switch to haiku model (faster, higher rate limits):');
+    lines.push('     Edit .claude/config.json:');
+    lines.push('     { "subagents": { "model": "haiku" } }');
+    lines.push('  4. Skip analysis for now:');
+    lines.push('     git commit --no-verify -m "your message"');
+    lines.push('');
+    lines.push('The hook will automatically retry once after 2 seconds.');
+
+    return lines.join('\n');
+};
+
 /**
  * Format rate limit error
  */
-const formatRateLimitError = ({ resetDate, minutesUntilReset }) => {
+const formatRateLimitError = (errorInfo) => {
+    const { resetDate, minutesUntilReset } = errorInfo;
     const lines = [];
 
     lines.push('❌ Claude API usage limit reached');
@@ -145,6 +226,7 @@ const formatRateLimitError = ({ resetDate, minutesUntilReset }) => {
         lines.push('  Limit should be reset now');
     }
 
+    lines.push(...formatTimingInfo(errorInfo));
     lines.push('');
     lines.push('Options:');
     lines.push('  1. Wait for rate limit to reset');
@@ -160,10 +242,12 @@ const formatRateLimitError = ({ resetDate, minutesUntilReset }) => {
 /**
  * Format authentication error
  */
-const formatAuthError = ({ exitCode }) => {
+const formatAuthError = (errorInfo) => {
+    const { exitCode } = errorInfo;
     const lines = [];
 
     lines.push('❌ Claude CLI authentication failed');
+    lines.push(...formatTimingInfo(errorInfo));
     lines.push('');
     lines.push('Possible causes:');
     lines.push('  1. Not logged in to Claude CLI');
@@ -181,10 +265,12 @@ const formatAuthError = ({ exitCode }) => {
 /**
  * Format network error
  */
-const formatNetworkError = ({ exitCode }) => {
+const formatNetworkError = (errorInfo) => {
+    const { exitCode } = errorInfo;
     const lines = [];
 
     lines.push('❌ Network error connecting to Claude API');
+    lines.push(...formatTimingInfo(errorInfo));
     lines.push('');
     lines.push('Possible causes:');
     lines.push('  1. No internet connection');
@@ -203,10 +289,12 @@ const formatNetworkError = ({ exitCode }) => {
 /**
  * Format invalid response error
  */
-const formatInvalidResponseError = ({ exitCode }) => {
+const formatInvalidResponseError = (errorInfo) => {
+    const { exitCode } = errorInfo;
     const lines = [];
 
     lines.push('❌ Claude returned invalid response');
+    lines.push(...formatTimingInfo(errorInfo));
     lines.push('');
     lines.push('This usually means:');
     lines.push('  - Claude did not return valid JSON');
@@ -223,12 +311,14 @@ const formatInvalidResponseError = ({ exitCode }) => {
 /**
  * Format generic error
  */
-const formatGenericError = ({ exitCode, stdout, stderr }) => {
+const formatGenericError = (errorInfo) => {
+    const { exitCode, stdout, stderr } = errorInfo;
     const lines = [];
 
     lines.push('❌ Claude CLI execution failed');
     lines.push('');
     lines.push(`Exit code: ${exitCode}`);
+    lines.push(...formatTimingInfo(errorInfo));
 
     if (stdout && stdout.trim()) {
         lines.push('');
@@ -261,6 +351,7 @@ const formatGenericError = ({ exitCode, stdout, stderr }) => {
  * @returns {boolean} True if error might resolve with retry
  */
 export const isRecoverableError = (errorInfo) => {
-    return errorInfo.type === ClaudeErrorType.RATE_LIMIT ||
+    return errorInfo.type === ClaudeErrorType.EXECUTION_ERROR ||
+           errorInfo.type === ClaudeErrorType.RATE_LIMIT ||
            errorInfo.type === ClaudeErrorType.NETWORK;
 };

package/lib/utils/prompt-builder.js

@@ -215,8 +215,8 @@ const formatFileSection = ({ path, diff, content, isNew }) => {
  * }
  */
 const buildAnalysisPrompt = async ({
-    templateName = 'CLAUDE_ANALYSIS_PROMPT_SONAR.md',
-    guidelinesName = 'CLAUDE_PRE_COMMIT_SONAR.md',
+    templateName = 'CLAUDE_ANALYSIS_PROMPT.md',
+    guidelinesName = 'CLAUDE_PRE_COMMIT.md',
     files = [],
     metadata = {},
     subagentConfig = null

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-git-hooks",
-    "version": "2.6.3",
+    "version": "2.8.0",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {

package/templates/{CLAUDE_ANALYSIS_PROMPT_SONAR.md → CLAUDE_ANALYSIS_PROMPT.md}

@@ -1,4 +1,4 @@
-ROLE:SeniorCodeReviewer,SonarQube-experienced
+ROLE:SeniorCodeReviewer,CodeQualityExpert
 TASK:Analyze code->JSON only
 CRITICAL:NoTextOutsideJSON,ValidJSON
 
@@ -44,6 +44,7 @@ OUTPUT_SCHEMA:
 ```
 
 RULES:
+- **FALSE_POSITIVE_PREVENTION**: Only report actual problems. Do not report improvements, positive changes, or routine maintenance as issues. Zero issues is a valid and positive outcome.
 - blockingIssues=ALWAYS_ARRAY_OF_OBJECTS(never_strings)
 - blockingIssues=ALL(details.severity∈{BLOCKER,CRITICAL})
 - Each_blockingIssue_MUST_have:description,file,line,method,severity

package/templates/{CLAUDE_PRE_COMMIT_SONAR.md → CLAUDE_PRE_COMMIT.md}

@@ -1,4 +1,13 @@
-# SONARQUBE_EVAL_CRITERIA
+# CODE_QUALITY_EVALUATION_CRITERIA
+
+## FALSE_POSITIVE_PREVENTION
+
+**IMPORTANT**: Only report actual problems, bugs, security issues, or code quality concerns.
+
+- Do NOT report improvements, positive changes, or routine maintenance as issues
+- It is perfectly acceptable to find ZERO issues - this is a positive outcome
+- When in doubt about whether something is an issue, err on the side of NOT reporting it
+- Focus on what could break, harm security, or degrade quality - not what could be "better"
 
 ## EXCEPTIONS_AND_ALLOWED_PATTERNS
 ### Spring Framework Patterns (NOT blocking issues)

package/templates/CUSTOMIZATION_GUIDE.md

@@ -149,7 +149,7 @@ A preset is a **self-contained package** that customizes claude-hooks for a spec
                          │
 ┌────────────────────────▼────────────────────────────────────┐
 │ 8. RESPONSE PROCESSED                                       │
-│    - JSON format (SonarQube-style)                          │
+│    - JSON format with structured results                    │
 │    - Quality gate: PASSED/FAILED                            │
 │    - Issues by severity: blocker, critical, major, minor    │
 │    - Commit proceeds or blocked                             │
@@ -382,7 +382,7 @@ Perform a comprehensive code quality analysis focusing on these areas:
 **Template**:
 
 ````markdown
-# SonarQube-Style Evaluation Criteria
+# Code Quality Evaluation Criteria
 
 ## Severity Levels
 
@@ -599,7 +599,7 @@ Please generate the following files:
 - This preset will be installed at: `templates/presets/{preset-name}/`
 - It should follow the same structure as existing presets in `templates/presets/backend/`
 - Users will select it with: `claude-hooks --set-preset {preset-name}`
-- The preset must output JSON in SonarQube format
+- The preset must output JSON with structured analysis results
 
 **Format**: Return each file's content as a separate code block with clear file headers.
 ```