claude-git-hooks 2.35.0 → 2.35.3

package/CHANGELOG.md

@@ -5,6 +5,58 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.35.3] - 2026-04-22
+
+### ✨ Added
+- Code Knowledge Library (`.library/`) with 25 reference books covering source modules — structured documentation with call signatures, I/O behavior, cross-references, and gotchas per module (#125-#131)
+- By-code index for navigating from source file paths to their reference books (`by-code/utils.md`, `by-code/commands.md`, `by-code/hooks.md`)
+- By-domain index with curated reading lists for four business workflows: commit pipeline, release management, PR analysis, and GitHub integration (`by-domain/`)
+- By-task-type index with step-by-step reading sequences for development tasks, starting with add-new-command guide (`by-task-type/`)
+- Dependency graph generator tool and path resolver for library infrastructure (`tools/`)
+- Book schema and token measurement infrastructure with calibration notes and category completeness validation
+- Classification report and category completeness report validating all 66 source modules against the 8-category taxonomy
+
+### 🐛 Fixed
+- Spotless linting timeouts and cmd.exe per-file mode on Windows — resolves batch-mode failures when Spotless wrapper is a `.cmd`/`.bat` file (#124, #125)
+
+
+## [2.35.2] - 2026-04-13
+
+### ✨ Added
+- Added Maven Wrapper (mvnw/mvnw.cmd) auto-detection for Spotless — bypasses cmd.exe metacharacter issues on Windows/WSL2
+- Added per-file execution mode for Spotless to avoid pipe (`|`) metacharacter in regex arguments on Windows
+- Added `env` option to `runTool`, `runToolFix`, and `runToolWithAutoFix` for passing extra environment variables to tool invocations
+- Added `configDir` to `_detectInProjectFiles` return value for downstream Maven Wrapper resolution
+
+### 🐛 Fixed
+- Fixed Spotless linter failing on Windows/WSL2 when multiple Java files are staged — `|` (pipe) in the `DspotlessFiles` regex was interpreted as a shell pipe by cmd.exe during batch script expansion
+
+
+## [2.35.1] - 2026-04-08
+
+### ✨ Added
+- Local binary resolution for linter tools — walks up from config directory to repo root, preferring project-installed binaries over npx to prevent version mismatches (#123)
+- Array-form `detectInProjectFile` for tool detection — Prettier and ESLint now recognized via config files (.prettierrc, .eslintrc.json, eslint.config.js, etc.) in addition to package.json dependencies
+- WSL2/Windows interop support for .cmd/.bat tool binaries, with proper cmd.exe metacharacter escaping
+- Source logging for linter tool resolution (remote/remote default/local) to make non-determinism visible
+- New `localBin` and `toolCwd` options for `runTool`/`runToolFix`/`runToolWithAutoFix` enabling direct binary execution and correct plugin resolution in monorepos
+
+### 🔧 Changed
+- Replaced `execSync` with `execFileSync` in tool-runner — args passed directly to process, preventing shell interpretation of regex metacharacters (e.g., `|` in Spotless patterns) and file path injection
+- Tool detection now requires project-level configuration when `detectInProjectFile` is defined — PATH-only presence no longer sufficient, preventing false positives (e.g., mvn in PATH treated as Spotless available)
+- Project file scanning starts from repo root instead of cwd, fixing detection when git hooks run from subdirectories
+- Increased judge timeout from 120s to 180s
+
+### 🐛 Fixed
+- Fixed tool auto-fix being attempted after execution failures (ENOENT, EACCES) by tracking `executionFailed` flag and skipping fix step
+- Fixed ENOENT handling in `runToolFix` — missing command binary now returns gracefully instead of being misinterpreted as a partial fix
+- Fixed `git add` in restage step to use `execFileSync` with proper argument array instead of shell string interpolation
+
+### 🔒 Security
+- Eliminated shell injection risk in tool execution by switching from `execSync` (shell-based) to `execFileSync` (direct process spawn)
+- Added `_escapeCmdMeta()` and `_prepareExec()` for safe cmd.exe argument passing when executing .cmd/.bat files on Windows/WSL
+
+
 ## [2.35.0] - 2026-03-27
 
 ### ✨ Added

package/CLAUDE.md

@@ -217,18 +217,19 @@ preset config (.claude/presets/{name}/config.json)  ← HIGHEST PRIORITY
 | Orchestrator threshold | 3 files | Commits with ≥3 files use Opus orchestration        |
 | Orchestrator model     | opus    | Internal constant — not user-configurable           |
 | Orchestrator timeout   | 60s     | Lightweight call (file overview only)               |
-| Analysis timeout       | 300s    | Per-batch timeout                                   |
+| Analysis timeout       | 360s    | Per-batch timeout                                   |
 | Commit msg timeout     | 300s    | Message generation timeout                          |
 | PR metadata timeout    | 180s    | Engine default (reads config)                       |
 | Judge model            | sonnet  | Default, configurable via `config.judge.model`      |
-| Judge timeout          | 120s    | Per-judge call timeout                              |
+| Judge timeout          | 360s    | Per-judge call timeout                              |
 | PR analysis model      | sonnet  | Default, configurable via `config.prAnalysis.model` |
 | PR analysis timeout    | 300s    | Per-analysis Claude call                            |
 | Linting enabled        | true    | Runs linters before Claude analysis                 |
 | Linting auto-fix       | true    | Auto-fix and re-stage files                         |
 | Linting fail on error  | true    | Block commit on linting errors                      |
 | Linting fail on warn   | false   | Do not block on warnings                            |
-| Linting timeout        | 30s     | Per-linter timeout                                  |
+| Linting timeout        | 30s     | Per-linter timeout (tool-specific overrides if higher) |
+| Spotless timeout       | 120s    | Per-invocation; overrides config default             |
 
 **Judge behavior (v2.20.0):**
 
@@ -379,6 +380,10 @@ git commit
     → for each tool (formatters first, then linters):
         isToolAvailable() → not found? warn + install hint → skip
         filterFilesByTool() → matching files
+        → timeout = max(config.linting.timeout, toolDef.timeout)
+        → perFile tools (Spotless): resolve command path
+            .cmd/.bat → per-file mode (cmd.exe pipe safety)
+            otherwise → batch mode (single JVM startup)
         runToolWithAutoFix() → check → auto-fix → re-stage → re-check
     → unfixable issues forwarded to judge
   ↓
@@ -1350,7 +1355,7 @@ Recurring patterns validated across 15+ automation sessions. Apply these in new
     - Enables centralized output control and debug mode
 
 9. **DO NOT execute Claude CLI without timeout**
-    - Always configure timeout (default: 150s analysis, 180s commit msg)
+    - Always configure timeout (default: 360s analysis, 300s commit msg)
     - Timeout configurable in `.claude/config.json`
 
 10. **DO NOT ignore platform-specific issues**

package/lib/config.js

@@ -33,7 +33,7 @@ const HARDCODED = {
     analysis: {
         maxFileSize: 1000000, // 1MB - sufficient for most files
         maxFiles: 30, // Reasonable limit per commit
-        timeout: 300000, // 5 minutes - adequate for Claude API
+        timeout: 360000, // 6 minutes - adequate for Claude API
         contextLines: 3, // Git default
         ignoreExtensions: [] // Can be set in advanced config only
     },

package/lib/utils/judge.js

@@ -28,7 +28,7 @@ import logger from './logger.js';
 import { recordMetric } from './metrics.js';
 
 const JUDGE_DEFAULT_MODEL = 'sonnet';
-const JUDGE_TIMEOUT = 120000;
+const JUDGE_TIMEOUT = 360000;
 
 /**
  * Applies a single search/replace fix to a file and stages it

package/lib/utils/linter-runner.js

@@ -15,6 +15,8 @@
  * - logger: Debug and error logging
  */
 
+import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import {
     isToolAvailable,
@@ -23,6 +25,7 @@ import {
     displayToolResult
 } from './tool-runner.js';
 import { getRepoRoot } from './git-operations.js';
+import { which } from './which-command.js';
 import { fetchRemoteConfig } from './remote-config.js';
 import logger from './logger.js';
 
@@ -212,6 +215,36 @@ export function filesToSpotlessRegex(files) {
     return escaped.join('|');
 }
 
+/**
+ * Find Maven Wrapper (mvnw/mvnw.cmd) near the pom.xml directory.
+ * Maven Wrapper invokes Java directly, bypassing cmd.exe — avoids
+ * metacharacter issues with | in command-line args on Windows/WSL2.
+ *
+ * @param {string} configDir - Directory containing pom.xml
+ * @returns {string|null} Path to mvnw/mvnw.cmd, or null if not found
+ */
+function _findMavenWrapper(configDir) {
+    if (!configDir) return null;
+
+    // On Windows, prefer .cmd (executable) over extensionless (bash script).
+    // On Linux/macOS/WSL, prefer extensionless (native) over .cmd.
+    const candidates = os.platform() === 'win32'
+        ? [path.join(configDir, 'mvnw.cmd'), path.join(configDir, 'mvnw')]
+        : [path.join(configDir, 'mvnw'), path.join(configDir, 'mvnw.cmd')];
+
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate)) {
+            logger.debug('linter-runner - _findMavenWrapper',
+                'Found Maven Wrapper', { path: candidate });
+            return candidate;
+        }
+    }
+
+    logger.debug('linter-runner - _findMavenWrapper',
+        'No Maven Wrapper found', { configDir });
+    return null;
+}
+
 /**
  * Available linter tool definitions
  * @type {Object<string, import('./tool-runner.js').ToolDefinition>}
@@ -223,14 +256,24 @@ export const LINTER_TOOLS = {
         args: (files) => ['prettier', '--check', ...files],
         fixArgs: (files) => ['prettier', '--write', ...files],
         detectCommand: 'prettier',
-        detectInProjectFile: {
-            filename: 'package.json',
-            check: (content) => {
-                const pkg = JSON.parse(content);
-                const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-                return 'prettier' in allDeps;
-            }
-        },
+        // Array form: multiple detection strategies. First match wins.
+        // Prettier may be a direct dep, or bundled via meta-frameworks,
+        // or only indicated by a config file.
+        detectInProjectFile: [
+            {
+                filename: 'package.json',
+                check: (content) => {
+                    const pkg = JSON.parse(content);
+                    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+                    return 'prettier' in allDeps;
+                }
+            },
+            { filename: '.prettierrc', check: () => true },
+            { filename: '.prettierrc.json', check: () => true },
+            { filename: '.prettierrc.js', check: () => true },
+            { filename: 'prettier.config.js', check: () => true },
+            { filename: 'prettier.config.mjs', check: () => true }
+        ],
         installHint: 'npm install --save-dev prettier',
         extensions: ['.js', '.jsx', '.ts', '.tsx', '.css', '.scss', '.html', '.json', '.md', '.yaml', '.yml'],
         parseOutput: parsePrettierOutput,
@@ -242,14 +285,24 @@ export const LINTER_TOOLS = {
         args: (files) => ['eslint', '--format', 'json', '--no-error-on-unmatched-pattern', ...files],
         fixArgs: (files) => ['eslint', '--fix', '--no-error-on-unmatched-pattern', ...files],
         detectCommand: 'eslint',
-        detectInProjectFile: {
-            filename: 'package.json',
-            check: (content) => {
-                const pkg = JSON.parse(content);
-                const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-                return 'eslint' in allDeps;
-            }
-        },
+        // Array form: ESLint may be a direct dep, bundled via react-scripts/next,
+        // indicated by eslintConfig in package.json, or by a config file.
+        detectInProjectFile: [
+            {
+                filename: 'package.json',
+                check: (content) => {
+                    const pkg = JSON.parse(content);
+                    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+                    return 'eslint' in allDeps || 'eslintConfig' in pkg;
+                }
+            },
+            { filename: '.eslintrc.json', check: () => true },
+            { filename: '.eslintrc.js', check: () => true },
+            { filename: '.eslintrc.yml', check: () => true },
+            { filename: '.eslintrc', check: () => true },
+            { filename: 'eslint.config.js', check: () => true },
+            { filename: 'eslint.config.mjs', check: () => true }
+        ],
         installHint: 'npm install --save-dev eslint',
         extensions: ['.js', '.jsx', '.ts', '.tsx'],
         parseOutput: parseEslintOutput,
@@ -272,7 +325,14 @@ export const LINTER_TOOLS = {
         installHint: 'Add spotless-maven-plugin to pom.xml (see https://github.com/diffplug/spotless)',
         extensions: ['.java'],
         parseOutput: parseSpotlessOutput,
-        timeout: 60000
+        timeout: 120000,
+        // Run per-file to avoid | (pipe) in regex on Windows.
+        // filesToSpotlessRegex joins files with | for regex alternation.
+        // cmd.exe interprets | as a pipe at every expansion level —
+        // ^ escaping is consumed by the first cmd.exe parse, and %VAR% expansion
+        // in batch scripts (mvn.cmd) re-exposes unescaped | to a second parse.
+        // Per-file execution ensures each regex has at most one file pattern (no |).
+        perFile: true
     },
     sqlfluff: {
         name: 'sqlfluff',
@@ -338,6 +398,13 @@ export async function getLinterToolsForPreset(presetName) {
         });
     }
 
+    // User-visible source logging — makes non-determinism visible when remote config
+    // flips between available and unavailable across invocations
+    const hasPresetInRemote = remoteConfig?.presetTools?.[presetName];
+    const hasDefaultInRemote = remoteConfig?.presetTools?.default;
+    const source = hasPresetInRemote ? 'remote' : hasDefaultInRemote ? 'remote default' : 'local';
+    logger.info(`Linter tools [${source}]: ${toolNames.join(', ')}`);
+
     return toolNames.map((name) => LINTER_TOOLS[name]).filter(Boolean);
 }
 
@@ -395,14 +462,77 @@ export async function runLinters(files, config, presetName = 'default') {
             continue;
         }
 
-        // Run tool with optional auto-fix
-        const result = runToolWithAutoFix(toolDef, matchingFiles, {
+        // Maven Wrapper: prefer mvnw when available (invokes Java directly, bypasses cmd.exe).
+        // Cannot reuse localBin — _prepareToolCall strips args[0] for npx tools,
+        // but Spotless args are Maven goals (spotless:check), not a tool name to strip.
+        // Shallow-clone toolDef with wrapper as command instead.
+        let effectiveToolDef = toolDef;
+        if (!availability.localBin && availability.configDir && toolDef.command === 'mvn') {
+            const wrapper = _findMavenWrapper(availability.configDir);
+            if (wrapper) {
+                effectiveToolDef = { ...toolDef, command: wrapper };
+                logger.info(`Using Maven Wrapper: ${path.basename(wrapper)}`);
+            }
+        }
+
+        // Use the higher of config timeout and tool-specific timeout.
+        // Spotless (120s) should not be silently capped to the config default (30s).
+        const effectiveTimeout = Math.max(timeout, effectiveToolDef.timeout || 0);
+
+        const toolOpts = {
             autoFix,
-            timeout,
-            restage: true
-        });
+            timeout: effectiveTimeout,
+            restage: true,
+            localBin: availability.localBin,
+            toolCwd: availability.configDir
+        };
+
+        // Per-file execution: run once per file to avoid | (pipe) in command args.
+        // On Windows, cmd.exe interprets | as a pipe at every expansion level —
+        // ^ escaping is consumed at the first parse, and %VAR% expansion in batch
+        // scripts (mvn.cmd) re-exposes unescaped | to a second parse.
+        // Running per-file ensures each invocation has a single-file regex (no |).
+        //
+        // However, per-file mode is ONLY needed when the command routes through
+        // cmd.exe (.cmd/.bat files). Direct executables and bash scripts (e.g.,
+        // mvnw) pass args to the process directly — | is never interpreted as a pipe.
+        // Batch mode avoids N separate JVM startups, which is critical for Spotless
+        // on Windows/WSL where each startup adds significant overhead.
+        let needsPerFile = effectiveToolDef.perFile && matchingFiles.length > 1;
+        if (needsPerFile) {
+            const resolvedCmd = effectiveToolDef.command.includes(path.sep)
+                ? effectiveToolDef.command
+                : (which(effectiveToolDef.command) || effectiveToolDef.command);
+            if (!/\.(cmd|bat)$/i.test(resolvedCmd)) {
+                needsPerFile = false;
+                logger.debug('linter-runner - runLinters',
+                    `${effectiveToolDef.name} command bypasses cmd.exe, using batch mode`,
+                    { command: resolvedCmd });
+            }
+        }
+
+        if (needsPerFile) {
+            logger.debug('linter-runner - runLinters',
+                `Running ${effectiveToolDef.name} per-file (cmd.exe path)`,
+                { fileCount: matchingFiles.length });
+
+            const perFileResults = matchingFiles.map((file) =>
+                runToolWithAutoFix(effectiveToolDef, [file], toolOpts)
+            );
 
-        results.push(result);
+            results.push({
+                tool: effectiveToolDef.name,
+                skipped: false,
+                errors: perFileResults.flatMap((r) => r.errors),
+                warnings: perFileResults.flatMap((r) => r.warnings),
+                fixedCount: perFileResults.reduce((sum, r) => sum + r.fixedCount, 0),
+                fixedFiles: perFileResults.flatMap((r) => r.fixedFiles)
+            });
+        } else {
+            // Normal batch execution
+            const result = runToolWithAutoFix(effectiveToolDef, matchingFiles, toolOpts);
+            results.push(result);
+        }
     }
 
     // Aggregate totals

package/lib/utils/tool-runner.js

@@ -17,11 +17,13 @@
  * - logger: Debug and error logging
  */
 
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { which } from './which-command.js';
 import { walkDirectoryTree } from './file-utils.js';
+import { getRepoRoot } from './git-operations.js';
 import logger from './logger.js';
 
 /**
@@ -31,11 +33,13 @@ import logger from './logger.js';
  * @property {function(string[]): string[]} args - Build args for check mode
  * @property {function(string[]): string[]} [fixArgs] - Build args for auto-fix mode
  * @property {string} detectCommand - Binary to check via which() (e.g., 'eslint')
+ * @property {Object|Object[]} [detectInProjectFile] - Project file indicator(s). Single { filename, check } or array of them. When defined, project file validation is mandatory — PATH alone is not sufficient.
  * @property {string} [detectFallback] - Fallback path to check (e.g., 'node_modules/.bin/eslint')
  * @property {string} installHint - Install instruction shown when tool is missing
  * @property {string[]} extensions - File extensions this tool handles
  * @property {function(string): Object} parseOutput - Parse stdout into structured results
  * @property {number} [timeout] - Per-tool timeout in ms (default from config)
+ * @property {function(string[]): Object} [getEnv] - Build extra env vars for invocation (e.g., MAVEN_OPTS for Spotless regex)
  */
 
 /**
@@ -62,38 +66,51 @@ import logger from './logger.js';
 /**
  * Check if a tool is available on the system
  *
+ * When detectInProjectFile is defined, the tool requires project-level
+ * configuration (e.g., spotless-maven-plugin in pom.xml, eslint in package.json).
+ * In that case, finding the command binary in PATH is necessary but NOT sufficient —
+ * the project must declare the tool. This prevents false positives like mvn in PATH
+ * being treated as "Spotless available" when the project has no Spotless plugin.
+ *
  * @param {ToolDefinition} toolDef - Tool definition
  * @returns {{ available: boolean, path: string|null }} Availability info
  */
 export function isToolAvailable(toolDef) {
-    // Strategy 1: Check detectCommand in PATH (global install)
-    const resolved = which(toolDef.detectCommand);
-    if (resolved) {
-        logger.debug('tool-runner - isToolAvailable', `Found ${toolDef.name} in PATH`, { path: resolved });
-        return { available: true, path: resolved };
-    }
-
-    // Strategy 2: Check project files for the tool as a dependency
-    // Why: local installs (npm install --save-dev) live in node_modules/.bin,
-    // not in PATH. npx resolves them at runtime, so we just need to confirm
-    // the tool is declared in a project file (package.json deps or pom.xml plugin).
-    // Uses walkDirectoryTree (same walker as version-manager) to scan up to 3 levels.
+    // Strategy 1: Tools that require project-level configuration
+    // The detectInProjectFile field signals that detectCommand (e.g., 'mvn') is a
+    // build tool, not the tool itself. Project file validation is mandatory.
     if (toolDef.detectInProjectFile) {
         const found = _detectInProjectFiles(toolDef);
         if (found) {
-            // Tool is configured but the command binary is missing
+            // Tool is configured but not runnable (binary missing or not installed locally)
             if (found.configured && !found.available) {
                 logger.debug('tool-runner - isToolAvailable',
-                    `${toolDef.name} configured but '${found.missingCommand}' not in PATH`
+                    `${toolDef.name} configured but not runnable`, {
+                        missingCommand: found.missingCommand || null
+                    }
                 );
                 return {
                     available: false,
                     path: null,
-                    installHint: `${toolDef.name} is configured in your project but '${found.missingCommand}' is not in PATH. Install it and ensure it's accessible from your terminal.`
+                    configured: true,
+                    installHint: found.installHint || `${toolDef.name} is configured in your project but '${found.missingCommand}' is not in PATH. Install it and ensure it's accessible from your terminal.`
                 };
             }
             return found;
         }
+        // Project file not found or tool not declared → not available for this project
+        logger.debug('tool-runner - isToolAvailable',
+            `${toolDef.name} not configured in project files`
+        );
+        return { available: false, path: null };
+    }
+
+    // Strategy 2: Simple tools without project file requirements (e.g., sqlfluff)
+    // PATH detection is sufficient — the tool is standalone.
+    const resolved = which(toolDef.detectCommand);
+    if (resolved) {
+        logger.debug('tool-runner - isToolAvailable', `Found ${toolDef.name} in PATH`, { path: resolved });
+        return { available: true, path: resolved };
     }
 
     logger.debug('tool-runner - isToolAvailable', `${toolDef.name} not found`);
@@ -101,17 +118,81 @@ export function isToolAvailable(toolDef) {
 }
 
 /**
- * Scan project files (package.json, pom.xml) up to 3 levels deep
- * to detect if a tool is declared as a dependency or plugin.
+ * Find a tool binary in local node_modules/.bin, walking up from configDir to rootDir.
+ * Prevents npx from downloading or using a globally cached version that may be
+ * incompatible with the project's configuration format.
+ *
+ * @param {string} command - Binary name to find (e.g., 'eslint', 'prettier')
+ * @param {string} configDir - Directory where the tool's config was found
+ * @param {string} rootDir - Repo root (stop searching here)
+ * @returns {string|null} Path to local binary, or null if not found
+ */
+function _findLocalBinary(command, configDir, rootDir) {
+    let dir = configDir;
+
+    while (dir) {
+        const binDir = path.join(dir, 'node_modules', '.bin');
+        // Check both extensionless and .cmd — WSL repos on Windows filesystem
+        // may have .cmd files from a Windows npm install
+        // On Windows, prefer .cmd (executable) over extensionless (bash script).
+        // On Linux/macOS, prefer extensionless (native) over .cmd.
+        const candidates = os.platform() === 'win32'
+            ? [path.join(binDir, `${command}.cmd`), path.join(binDir, command)]
+            : [path.join(binDir, command), path.join(binDir, `${command}.cmd`)];
+
+        for (const candidate of candidates) {
+            if (fs.existsSync(candidate)) {
+                return candidate;
+            }
+        }
+
+        // Stop at repo root
+        if (dir === rootDir) break;
+        const parent = path.dirname(dir);
+        if (parent === dir) break; // filesystem root
+        dir = parent;
+    }
+
+    return null;
+}
+
+/**
+ * Scan project files (package.json, pom.xml, config files) up to 3 levels deep
+ * to detect if a tool is declared as a dependency, plugin, or has a config file.
+ *
+ * detectInProjectFile can be a single { filename, check } or an array of them.
+ * Array form allows multiple detection strategies (e.g., ESLint: check package.json
+ * deps, eslintConfig key, OR .eslintrc.json existence). First match wins.
  *
  * @param {ToolDefinition} toolDef - Tool definition with detectInProjectFile
  * @returns {{ available: boolean, path: string|null } | null} Result or null if not found
  */
 export function _detectInProjectFiles(toolDef) {
-    const { filename, check } = toolDef.detectInProjectFile;
+    // Normalize to array — supports both single object and array of indicators
+    const checks = Array.isArray(toolDef.detectInProjectFile)
+        ? toolDef.detectInProjectFile
+        : [toolDef.detectInProjectFile];
+
     let found = false;
+    let configDir = null;
+
+    // Use repo root instead of cwd — git hooks may run from subdirectories
+    // and pom.xml / package.json at repo root could be beyond maxDepth from a deep cwd.
+    let startDir;
+    try {
+        startDir = getRepoRoot();
+    } catch {
+        startDir = process.cwd();
+    }
+
+    logger.debug('tool-runner - _detectInProjectFiles', 'Scanning from directory', {
+        startDir,
+        cwd: process.cwd(),
+        usingRepoRoot: startDir !== process.cwd(),
+        filenames: checks.map((c) => c.filename)
+    });
 
-    walkDirectoryTree(process.cwd(), {
+    walkDirectoryTree(startDir, {
         maxDepth: 3,
         ignoreSet: new Set([
             '.git', 'node_modules', 'target', 'build', 'dist',
@@ -119,17 +200,21 @@ export function _detectInProjectFiles(toolDef) {
         ]),
         onFile: (entry, fullPath) => {
             if (found) return; // short-circuit after first match
-            if (entry.name === filename) {
-                try {
-                    const content = fs.readFileSync(fullPath, 'utf8');
-                    if (check(content)) {
-                        logger.debug('tool-runner - _detectInProjectFiles',
-                            `Found ${toolDef.name} in ${path.relative(process.cwd(), fullPath)}`
-                        );
-                        found = true;
+            for (const { filename, check } of checks) {
+                if (entry.name === filename) {
+                    try {
+                        const content = fs.readFileSync(fullPath, 'utf8');
+                        if (check(content)) {
+                            logger.debug('tool-runner - _detectInProjectFiles',
+                                `Found ${toolDef.name} in ${path.relative(startDir, fullPath)}`
+                            );
+                            found = true;
+                            configDir = path.dirname(fullPath);
+                            return;
+                        }
+                    } catch {
+                        // File read error — skip
                     }
-                } catch {
-                    // File read error — skip
                 }
             }
         }
@@ -140,24 +225,109 @@ export function _detectInProjectFiles(toolDef) {
     }
 
     // Project file declares the tool, but can we actually run the command?
-    // npx-based tools (eslint, etc.) are resolved by npx at runtime — always OK.
-    // Non-npx tools (mvn, sqlfluff, etc.) need the command binary in PATH.
-    if (toolDef.command !== 'npx') {
-        const cmdResolved = which(toolDef.command);
-        if (!cmdResolved) {
+    if (toolDef.command === 'npx') {
+        // npx-based tools: verify the package is installed locally.
+        // Without this, npx may download or use a globally cached version
+        // that's incompatible with the project's config (e.g., ESLint v10
+        // when the project uses .eslintrc.* from v8).
+        const localBin = _findLocalBinary(toolDef.detectCommand, configDir, startDir);
+        if (localBin) {
             logger.debug('tool-runner - _detectInProjectFiles',
-                `${toolDef.name} configured in project but '${toolDef.command}' not in PATH`
-            );
-            return {
-                available: false,
-                path: null,
-                configured: true,
-                missingCommand: toolDef.command
-            };
+                `Found local ${toolDef.name} binary`, { path: localBin });
+            return { available: true, path: toolDef.command, localBin, configDir };
         }
+        logger.debug('tool-runner - _detectInProjectFiles',
+            `${toolDef.name} configured but not installed locally`);
+        return {
+            available: false,
+            path: null,
+            configured: true,
+            installHint: `${toolDef.name} config found but the package is not installed locally. Run: ${toolDef.installHint}`
+        };
+    }
+
+    // Non-npx tools (mvn, sqlfluff, etc.) need the command binary in PATH.
+    const cmdResolved = which(toolDef.command);
+    if (!cmdResolved) {
+        logger.debug('tool-runner - _detectInProjectFiles',
+            `${toolDef.name} configured in project but '${toolDef.command}' not in PATH`
+        );
+        return {
+            available: false,
+            path: null,
+            configured: true,
+            missingCommand: toolDef.command
+        };
+    }
+
+    return { available: true, path: toolDef.command, configDir };
+}
+
+/**
+ * Resolve a tool's command to an absolute path.
+ * execFileSync bypasses the shell, so commands like 'npx' or 'mvn' that live
+ * in nvm/shell-initialized paths won't be found via process.env.PATH alone.
+ * which() uses the platform shell (which/where) to resolve the full path.
+ *
+ * @param {string} command - Command name (e.g., 'npx', 'mvn', 'git')
+ * @returns {string} Resolved path, or original command as fallback
+ */
+function _resolveCommand(command) {
+    const resolved = which(command);
+    if (resolved) {
+        logger.debug('tool-runner - _resolveCommand', `Resolved '${command}' to '${resolved}'`);
+        return resolved;
     }
+    logger.debug('tool-runner - _resolveCommand', `Could not resolve '${command}', using as-is`);
+    return command;
+}
 
-    return { available: true, path: toolDef.command };
+/**
+ * Escape cmd.exe metacharacters with ^ so they are treated as literals.
+ * Required when passing args through cmd.exe /c (e.g., for .cmd/.bat files).
+ * Without escaping, characters like | are interpreted as pipes by cmd.exe.
+ *
+ * @param {string} arg - Single argument string
+ * @returns {string} Escaped argument safe for cmd.exe
+ */
+function _escapeCmdMeta(arg) {
+    // ^ must be escaped first to avoid double-escaping
+    return arg.replace(/\^/g, '^^')
+        .replace(/%/g, '%%')
+        .replace(/&/g, '^&')
+        .replace(/\|/g, '^|')
+        .replace(/</g, '^<')
+        .replace(/>/g, '^>')
+        .replace(/\(/g, '^(')
+        .replace(/\)/g, '^)');
+}
+
+/**
+ * Prepare command and args for execFileSync when the resolved command is a
+ * .cmd/.bat file. These are batch scripts that must run through cmd.exe —
+ * execFileSync bypasses the shell, so direct execution throws EINVAL
+ * (CVE-2024-27980) on native Windows, or pipes args through cmd.exe on WSL
+ * where Windows interop auto-routes .cmd files.
+ *
+ * Detection is by file extension, NOT os.platform(), because WSL2 reports
+ * 'linux' but resolves Windows tools (npx.cmd, mvn.cmd) via PATH interop.
+ *
+ * Args are escaped for cmd.exe metacharacters (|, &, <, >, ^, (, ))
+ * to prevent shell interpretation (e.g., | in Spotless regex patterns).
+ *
+ * @param {string} command - Resolved command path
+ * @param {string[]} args - Command arguments
+ * @returns {{ command: string, args: string[] }} Adjusted for platform
+ */
+function _prepareExec(command, args) {
+    if (/\.(cmd|bat)$/i.test(command)) {
+        logger.debug('tool-runner - _prepareExec', 'Wrapping .cmd with cmd.exe /c', { command });
+        return {
+            command: process.env.ComSpec || 'cmd.exe',
+            args: ['/c', command, ...args.map(_escapeCmdMeta)]
+        };
+    }
+    return { command, args };
 }
 
 /**
@@ -174,6 +344,58 @@ export function filterFilesByTool(files, toolDef) {
     });
 }
 
+/**
+ * Resolve command, args, and cwd for a tool invocation.
+ * Shared by runTool and runToolFix to avoid duplication.
+ *
+ * When a local binary is provided, it replaces npx and the first arg (tool name)
+ * is stripped. When toolCwd is provided, files become absolute so they resolve
+ * correctly from the tool's config directory (needed for plugin resolution).
+ *
+ * @param {ToolDefinition} toolDef - Tool definition
+ * @param {string[]} rawArgs - Args from toolDef.args() or toolDef.fixArgs()
+ * @param {Object} options - Caller options (cwd, localBin, toolCwd)
+ * @param {string} cwd - Base working directory (repo root)
+ * @returns {{ exec: { command: string, args: string[] }, cwd: string, fullCommand: string }}
+ */
+function _prepareToolCall(toolDef, rawArgs, options, cwd) {
+    let resolvedCommand, execArgs;
+    if (options.localBin) {
+        resolvedCommand = options.localBin;
+        // rawArgs[0] is the tool name (e.g. 'eslint') as passed to npx.
+        // Strip it since localBin IS the tool — the wrapper is not needed.
+        // Contract: toolDef.args() must always place the tool name first.
+        execArgs = rawArgs.slice(1);
+        logger.debug('tool-runner - _prepareToolCall', `Using local binary for ${toolDef.name}`, {
+            localBin: options.localBin,
+            toolCwd: options.toolCwd || null
+        });
+    } else {
+        resolvedCommand = _resolveCommand(toolDef.command);
+        execArgs = rawArgs;
+    }
+
+    const exec = _prepareExec(resolvedCommand, execArgs);
+    const effectiveCwd = options.toolCwd || cwd;
+    const fullCommand = [exec.command, ...exec.args].join(' ');
+
+    return { exec, cwd: effectiveCwd, fullCommand };
+}
+
+/**
+ * When toolCwd is set, convert repo-relative file paths to absolute so they
+ * resolve correctly from the tool's config directory.
+ *
+ * @param {string[]} files - File paths (may be repo-relative)
+ * @param {string} cwd - Repo root (base for resolving relative paths)
+ * @param {string} [toolCwd] - Tool's config directory
+ * @returns {string[]} Adjusted file paths
+ */
+function _resolveFilePaths(files, cwd, toolCwd) {
+    if (!toolCwd) return files;
+    return files.map((f) => path.isAbsolute(f) ? f : path.resolve(cwd, f));
+}
+
 /**
  * Execute a tool on files and parse output
  *
@@ -182,13 +404,17 @@ export function filterFilesByTool(files, toolDef) {
  * @param {Object} options - Execution options
  * @param {number} [options.timeout] - Timeout in ms
  * @param {string} [options.cwd] - Working directory
+ * @param {string} [options.localBin] - Local binary path (bypasses npx resolution)
+ * @param {string} [options.toolCwd] - Run tool from this directory (for plugin resolution)
+ * @param {Object} [options.env] - Extra environment variables (merged with process.env)
  * @returns {ToolRunResult} Parsed result
  */
 export function runTool(toolDef, files, options = {}) {
     const { timeout = toolDef.timeout || 30000, cwd = process.cwd() } = options;
 
-    const args = toolDef.args(files);
-    const fullCommand = [toolDef.command, ...args].join(' ');
+    const effectiveFiles = _resolveFilePaths(files, cwd, options.toolCwd);
+    const rawArgs = toolDef.args(effectiveFiles);
+    const { exec, cwd: effectiveCwd, fullCommand } = _prepareToolCall(toolDef, rawArgs, options, cwd);
 
     logger.debug('tool-runner - runTool', `Executing ${toolDef.name}`, {
         command: fullCommand,
@@ -205,13 +431,23 @@ export function runTool(toolDef, files, options = {}) {
         fixedFiles: []
     };
 
+    // Build execFileSync options. When tool provides env overrides (e.g., MAVEN_OPTS
+    // for Spotless regex), merge them with process.env so PATH and other vars are preserved.
+    const execOptions = {
+        encoding: 'utf8',
+        timeout,
+        cwd: effectiveCwd,
+        stdio: ['pipe', 'pipe', 'pipe']
+    };
+    if (options.env) {
+        execOptions.env = { ...process.env, ...options.env };
+    }
+
     try {
-        const stdout = execSync(fullCommand, {
-            encoding: 'utf8',
-            timeout,
-            cwd,
-            stdio: ['pipe', 'pipe', 'pipe']
-        });
+        // execFileSync bypasses shell — args passed directly to process.
+        // Prevents shell interpretation of regex metacharacters (e.g., | in Spotless regex)
+        // and eliminates shell injection risk from file paths.
+        const stdout = execFileSync(exec.command, exec.args, execOptions);
 
         // Exit code 0 = no issues; parse anyway for warnings
         if (toolDef.parseOutput && stdout.trim()) {
@@ -225,8 +461,9 @@ export function runTool(toolDef, files, options = {}) {
             const parsed = toolDef.parseOutput(err.stdout);
             result.errors = parsed.errors || [];
             result.warnings = parsed.warnings || [];
-        } else if (err.killed) {
-            // Timeout
+        } else if (err.killed || err.code === 'ETIMEDOUT') {
+            // Timeout — err.killed for Node.js timeout, ETIMEDOUT for OS-level
+            // spawn timeout (common on Windows when cmd.exe → JVM startup is slow)
             logger.warning(`${toolDef.name} timed out after ${timeout}ms`);
             result.errors.push({
                 file: '',
@@ -234,13 +471,16 @@ export function runTool(toolDef, files, options = {}) {
                 message: `${toolDef.name} timed out after ${timeout / 1000}s`
             });
         } else {
-            // Genuine execution error
+            // Genuine execution error (ENOENT, EACCES, etc.)
             const stderr = err.stderr ? err.stderr.toString().trim() : '';
             logger.debug('tool-runner - runTool', `${toolDef.name} execution error`, {
                 exitCode: err.status,
+                code: err.code,
                 stderr
             });
 
+            result.executionFailed = true;
+
             // If no parseable output, treat as tool error
             if (!err.stdout) {
                 result.errors.push({
@@ -269,6 +509,9 @@ export function runTool(toolDef, files, options = {}) {
  * @param {number} [options.timeout] - Timeout in ms
  * @param {string} [options.cwd] - Working directory
  * @param {boolean} [options.restage] - Re-stage fixed files (default: true)
+ * @param {string} [options.localBin] - Local binary path (bypasses npx resolution)
+ * @param {string} [options.toolCwd] - Run tool from this directory (for plugin resolution)
+ * @param {Object} [options.env] - Extra environment variables (merged with process.env)
  * @returns {{ fixedFiles: string[], fixedCount: number }} Fix results
  */
 export function runToolFix(toolDef, files, options = {}) {
@@ -279,26 +522,37 @@ export function runToolFix(toolDef, files, options = {}) {
         return { fixedFiles: [], fixedCount: 0 };
     }
 
-    const args = toolDef.fixArgs(files);
-    const fullCommand = [toolDef.command, ...args].join(' ');
+    const effectiveFiles = _resolveFilePaths(files, cwd, options.toolCwd);
+    const rawArgs = toolDef.fixArgs(effectiveFiles);
+    const { exec, cwd: effectiveCwd, fullCommand } = _prepareToolCall(toolDef, rawArgs, options, cwd);
 
     logger.debug('tool-runner - runToolFix', `Auto-fixing with ${toolDef.name}`, {
         command: fullCommand,
         fileCount: files.length
     });
 
+    const execOptions = {
+        encoding: 'utf8',
+        timeout,
+        cwd: effectiveCwd,
+        stdio: ['pipe', 'pipe', 'pipe']
+    };
+    if (options.env) {
+        execOptions.env = { ...process.env, ...options.env };
+    }
+
     try {
-        execSync(fullCommand, {
-            encoding: 'utf8',
-            timeout,
-            cwd,
-            stdio: ['pipe', 'pipe', 'pipe']
-        });
+        execFileSync(exec.command, exec.args, execOptions);
     } catch (err) {
-        if (err.killed) {
+        if (err.killed || err.code === 'ETIMEDOUT') {
             logger.warning(`${toolDef.name} auto-fix timed out`);
             return { fixedFiles: [], fixedCount: 0 };
         }
+        // ENOENT = command binary not found (process never started, err.status is null)
+        if (err.code === 'ENOENT') {
+            logger.debug('tool-runner - runToolFix', `${toolDef.name} not found (ENOENT)`);
+            return { fixedFiles: [], fixedCount: 0 };
+        }
         // Distinguish "command not found" from "partial fix exited non-zero"
         // Exit code 1 with stderr containing "not recognized" or "not found" = command missing
         const stderr = err.stderr ? err.stderr.toString() : '';
@@ -323,7 +577,7 @@ export function runToolFix(toolDef, files, options = {}) {
     if (restage) {
         for (const file of files) {
             try {
-                execSync(`git add "${file}"`, { cwd, stdio: 'pipe' });
+                execFileSync(_resolveCommand('git'), ['add', file], { cwd, stdio: 'pipe' });
                 fixedFiles.push(file);
             } catch {
                 // File may not have changed; that's fine
@@ -348,6 +602,7 @@ export function runToolFix(toolDef, files, options = {}) {
  * @param {number} [options.timeout] - Timeout in ms
  * @param {string} [options.cwd] - Working directory
  * @param {boolean} [options.restage] - Re-stage after fix (default: true)
+ * @param {Object} [options.env] - Extra environment variables (merged with process.env)
  * @returns {ToolRunResult} Final result after optional fix
  */
 export function runToolWithAutoFix(toolDef, files, options = {}) {
@@ -358,7 +613,7 @@ export function runToolWithAutoFix(toolDef, files, options = {}) {
 
     // Step 2: If any issues (errors or warnings) and autoFix enabled, try to fix
     const hasIssues = initialResult.errors.length > 0 || initialResult.warnings.length > 0;
-    if (autoFix && toolDef.fixArgs && hasIssues) {
+    if (autoFix && toolDef.fixArgs && hasIssues && !initialResult.executionFailed) {
         logger.info(`🔧 Auto-fixing ${toolDef.name} issues...`);
 
         const fixResult = runToolFix(toolDef, files, options);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-git-hooks",
-    "version": "2.35.0",
+    "version": "2.35.3",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {
@@ -20,7 +20,9 @@
         "lint:fix": "eslint lib/ bin/claude-hooks --fix",
         "format": "prettier --write \"lib/**/*.js\" \"bin/**\" \"test/**/*.js\"",
         "precommit": "npm run lint && npm run test:smoke",
-        "prepublishOnly": "npm run test:all"
+        "prepublishOnly": "npm run test:all",
+        "library:tokens": "node .library/tools/measure-tokens.js",
+        "library:graph": "node .library/tools/generate-graph.js"
     },
     "keywords": [
         "git",
@@ -64,6 +66,8 @@
         "@types/jest": "^29.5.0",
         "eslint": "^8.57.1",
         "jest": "^29.7.0",
+        "js-tiktoken": "^1.0.18",
+        "madge": "^8.0.0",
         "prettier": "^3.2.0"
     }
 }

package/templates/CUSTOMIZATION_GUIDE.md

@@ -284,7 +284,7 @@ cd python-django
     "analysis": {
         "maxFileSize": 1000000,
         "maxFiles": 12,
-        "timeout": 180000
+        "timeout": 360000
     },
     "subagents": {
         "enabled": true,
@@ -308,7 +308,7 @@ cd python-django
   analysis: {
     maxFileSize: 1000000,  // 1MB
     maxFiles: 30,
-    timeout: 180000        // 3 minutes
+    timeout: 360000        // 6 minutes
   },
   subagents: {
     enabled: true,