claude-git-hooks 2.34.0 → 2.35.2

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.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
+- Prettier formatting support — auto-formats JS/TS/CSS/HTML/JSON/YAML/MD files before linting (format first, then lint)
+- Remote formatter configuration — preset-to-tools mapping fetched from centralized git-hooks-config repo, allowing team-wide control without releasing new versions
+- New `parsePrettierOutput()` function for parsing Prettier --check output into structured issues
+
+### 🔧 Changed
+- Linting pipeline now runs formatters (Prettier) before linters (ESLint) for consistent code style
+- Updated preset-to-tools mapping: frontend, fullstack, ai, and default presets now include Prettier
+- `getLinterToolsForPreset()` now fetches remote config with local fallback instead of using hardcoded mapping only
+- `runLinters()` and `checkLinterAvailability()` converted to async functions to support remote config fetching
+- Unfixable linting issues are now forwarded to the Claude judge for semantic resolution instead of blocking directly
+
+
 ## [2.34.0] - 2026-03-27
 
 ### ✨ Added

package/CLAUDE.md

@@ -6,14 +6,14 @@
 
 **Main use cases:**
 
-1. **Pre-commit linting**: Runs linters (ESLint, Spotless, sqlfluff) on staged files before Claude analysis — fast, deterministic, auto-fix enabled by default
+1. **Pre-commit linting**: Runs formatters and linters (Prettier, ESLint, Spotless, sqlfluff) on staged files before Claude analysis — fast, deterministic, auto-fix enabled by default
 2. **Pre-commit analysis**: Detects security issues, bugs, and code smells before each commit (blocks on CRITICAL/BLOCKER only)
 3. **Interactive analysis**: `claude-hooks analyze` - review all issues (INFO to BLOCKER) interactively before committing
 4. **Automatic messages**: Write `git commit -m "auto"` and Claude generates the message in Conventional Commits format with task-id extracted from branch
 5. **PR analysis**: `claude-hooks analyze-diff [branch]` generates title, description, and test plan for PRs
 6. **PR review**: `claude-hooks analyze-pr <url>` analyzes a GitHub PR with preset guidelines, Linear ticket enrichment, and posts review comments
 7. **PR creation**: `claude-hooks create-pr [branch]` creates the PR on GitHub with automatic metadata (reviewers from CODEOWNERS, labels by preset, merge strategy auto-detected from branch naming)
-8. **Linting**: `claude-hooks lint [paths...]` runs linters on staged files, directories, or specific files — supports ESLint, Spotless, sqlfluff per preset
+8. **Linting**: `claude-hooks lint [paths...]` runs formatters and linters on staged files, directories, or specific files — supports Prettier, ESLint, Spotless, sqlfluff per preset (remote config priority with local fallback)
 9. **Coupling detection**: `claude-hooks check-coupling` scans open PRs targeting a base branch, computes file overlap, and reports which features are coupled (share modified files) — helps TL make informed decisions before cutting a release
 10. **Shadow management**: `claude-hooks shadow <analyze|reset|sync>` manages the shadow branch lifecycle — analyze divergence vs main and active RC, reset shadow to a clean copy of main, or sync shadow with a source branch (RC, develop, feature)
 11. **Release creation**: `claude-hooks create-release <major|minor|patch>` creates a release-candidate branch from develop, bumps version files, commits, pushes, and deploys to shadow — replaces the 8 manual steps executed every Tuesday by the Tech Lead
@@ -86,7 +86,7 @@ claude-git-hooks/
 │   │   └── prepare-commit-msg.js     # Message generation - auto commit messages
 │   └── utils/                        # Reusable modules - shared logic
 │       ├── tool-runner.js            # Generic tool executor - resolve, spawn, parse, auto-fix (v2.34.0)
-│       ├── linter-runner.js          # Linter orchestration - preset mapping, ESLint/Spotless/sqlfluff (v2.34.0)
+│       ├── linter-runner.js          # Linter orchestration - preset mapping, Prettier/ESLint/Spotless/sqlfluff, remote config (v2.34.0)
 │       ├── analysis-engine.js        # Shared analysis logic - file data, 3-tier routing, results (v2.13.0+)
 │       ├── diff-analysis-orchestrator.js  # Intelligent batch orchestration via Opus (v2.20.0)
 │       ├── claude-client.js          # Claude CLI wrapper - spawn, retry, model override
@@ -183,6 +183,7 @@ preset config (.claude/presets/{name}/config.json)  ← HIGHEST PRIORITY
 **Team-wide remote config** ([`mscope-S-L/git-hooks-config`](https://github.com/mscope-S-L/git-hooks-config)):
 
 - `labels.json` — PR label rules (fetched by `remote-config.js`, consumed by `label-resolver.js`)
+- `formatters.json` — preset-to-tools mapping for linting/formatting (fetched by `remote-config.js`, consumed by `linter-runner.js`)
 - `permissions.json` — role-based authorization (fetched directly by `authorization.js`, fail-closed)
 - Changes take effect immediately across all governed repos — no tool update needed
 
@@ -319,7 +320,7 @@ consolidateResults()
 | `lib/cli-metadata.js`           | Command registry                | `commands`, `buildCommandMap()`, `generateCompletionData()`, `PRESET_NAMES`, `HOOK_NAMES`, `BUMP_TYPES`                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `lib/config.js`                 | Config system                   | `getConfig()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `tool-runner.js`                | Generic tool executor           | `isToolAvailable()`, `filterFilesByTool()`, `runTool()`, `runToolFix()`, `runToolWithAutoFix()`, `displayToolResult()` (v2.34.0)                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `linter-runner.js`              | Linter orchestration            | `runLinters()`, `displayLintResults()`, `checkLinterAvailability()`, `getLinterToolsForPreset()`, `LINTER_TOOLS`, `PRESET_LINTERS`, `parseEslintOutput()`, `parseSpotlessOutput()`, `parseSqlfluffOutput()`, `filesToSpotlessRegex()` (v2.34.0)                                                                                                                                                                                                                                                                                                            |
+| `linter-runner.js`              | Linter orchestration            | `runLinters()`, `displayLintResults()`, `checkLinterAvailability()`, `getLinterToolsForPreset()`, `LINTER_TOOLS`, `PRESET_LINTERS`, `parsePrettierOutput()`, `parseEslintOutput()`, `parseSpotlessOutput()`, `parseSqlfluffOutput()`, `filesToSpotlessRegex()` (v2.34.0)                                                                                                                                                                                                                                                                                   |
 | `analysis-engine.js`            | Shared analysis logic           | `buildFileData()`, `buildFilesData()`, `runAnalysis()`, `consolidateResults()`, `hasBlockingIssues()`, `hasAnyIssues()`, `displayResults()`, `displayIssueSummary()` (v2.13.0+)                                                                                                                                                                                                                                                                                                                                                                            |
 | `diff-analysis-orchestrator.js` | Intelligent batch orchestration | `orchestrateBatches()`, `buildFileOverview()`, `detectDependencies()` (v2.20.0)                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `claude-client.js`              | Claude CLI wrapper              | `analyzeCode()`, `executeClaudeWithRetry()`, `extractJSON()` — spawn, retry, model override                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -359,8 +360,8 @@ consolidateResults()
 7. **Adapter Pattern**: `git-operations.js` abstracts git commands into JS functions
 8. **Singleton Pattern**: `config.js` loads configuration once per execution
 9. **Guard Pattern**: `authorization.js` — fail-closed gate in `bin/claude-hooks` before command dispatch; static `PROTECTED_COMMANDS` set avoids API calls for unprotected commands; permissions sourced from `mscope-S-L/git-hooks-config/permissions.json`
-10. **Remote Config Pattern**: `remote-config.js` — fetches JSON from `mscope-S-L/git-hooks-config`, caches per-process (including nulls), graceful degradation (warn + return null); `label-resolver.js` — callers receive config via dependency injection and decide fallback
-11. **Pipeline Pattern**: `tool-runner.js` + `linter-runner.js` — generic tool execution infrastructure; linters (and future formatters) share the same resolve → spawn → parse → fix → re-stage pipeline. Tool definitions are data objects, not classes.
+10. **Remote Config Pattern**: `remote-config.js` — fetches JSON from `mscope-S-L/git-hooks-config`, caches per-process (including nulls), graceful degradation (warn + return null); `label-resolver.js` and `linter-runner.js` — callers fetch remote config and decide fallback (`labels.json` for PR labels, `formatters.json` for preset-to-tools mapping)
+11. **Pipeline Pattern**: `tool-runner.js` + `linter-runner.js` — generic tool execution infrastructure; formatters (Prettier) and linters (ESLint, Spotless, sqlfluff) share the same resolve → spawn → parse → fix → re-stage pipeline. Tool definitions are data objects, not classes. Preset-to-tools mapping fetched from `mscope-S-L/git-hooks-config/formatters.json` (remote config priority, local fallback).
 
 ### Key Data Flows
 
@@ -372,13 +373,14 @@ git commit
   → filters by preset extensions + size
   ↓
   → LINTING STEP (fast, deterministic)
-    → getLinterToolsForPreset(presetName) → applicable linters
-    → for each linter:
+    → getLinterToolsForPreset(presetName):
+        1. fetchRemoteConfig('formatters.json') → remote presetTools mapping
+        2. fallback to local PRESET_LINTERS if remote unavailable
+    → for each tool (formatters first, then linters):
         isToolAvailable() → not found? warn + install hint → skip
         filterFilesByTool() → matching files
         runToolWithAutoFix() → check → auto-fix → re-stage → re-check
-    → if failOnError && errors remain → exit 1 (COMMIT BLOCKED)
-    → if failOnWarning && warnings → exit 1 (COMMIT BLOCKED)
+    → unfixable issues forwarded to judge
   ↓
   → continues to Claude analysis
 ```

package/README.md

@@ -82,6 +82,43 @@ export GITHUB_TOKEN="ghp_..."
 
 Create token at https://github.com/settings/tokens with scopes: `repo`, `read:org`
 
+### Linting & Formatting
+
+Runs formatters and linters on staged files automatically during pre-commit, or on demand:
+
+```bash
+# Lint staged files (default)
+claude-hooks lint
+
+# Lint all files in a directory
+claude-hooks lint src/
+
+# Lint specific files
+claude-hooks lint file1.js file2.java
+
+# Mix of directories and files
+claude-hooks lint src/ lib/utils/ file.js
+```
+
+**Tools per preset** (configured via [remote config](https://github.com/mscope-S-L/git-hooks-config)):
+
+| Preset      | Tools                         |
+| ----------- | ----------------------------- |
+| `frontend`  | Prettier, ESLint              |
+| `backend`   | Spotless                      |
+| `fullstack` | Prettier, ESLint, Spotless    |
+| `database`  | sqlfluff                      |
+| `ai`        | Prettier, ESLint              |
+| `default`   | Prettier, ESLint              |
+
+**Behavior:**
+
+- Formatters run first (Prettier), then linters (ESLint) — format before lint
+- Auto-fix enabled by default — fixes and re-stages files automatically
+- Missing tools are skipped with install instructions (never blocks)
+- Unfixable issues are forwarded to the Claude judge for semantic resolution
+- Tool-to-preset mapping is fetched from remote config (team-controlled, no release needed)
+
 ### Analyze Code (Interactive Review)
 
 Run interactive code analysis before committing:

package/lib/commands/install.js

@@ -673,7 +673,7 @@ export async function runInstall(args) {
         const presetName = config.preset || 'default';
         if (config.linting?.enabled !== false) {
             const { checkLinterAvailability } = await import('../utils/linter-runner.js');
-            checkLinterAvailability(presetName);
+            await checkLinterAvailability(presetName);
         }
     } catch {
         // Non-fatal — linter check failure should not block installation

package/lib/commands/lint.js

@@ -170,7 +170,7 @@ export async function runLint(args = []) {
 
     info(`🎯 Linting ${filesToLint.length} file(s) with '${metadata.displayName}' preset`);
 
-    const lintResult = runLinters(filesToLint, config, presetName);
+    const lintResult = await runLinters(filesToLint, config, presetName);
     displayLintResults(lintResult);
 
     // Exit with error code if linting failed

package/lib/hooks/pre-commit.js

@@ -152,7 +152,7 @@ const main = async () => {
             logger.info('🔍 Running linters...');
             const lintStartTime = Date.now();
             const filePaths = validFiles.map((f) => (typeof f === 'string' ? f : f.path));
-            const lintResult = runLinters(filePaths, config, presetName);
+            const lintResult = await runLinters(filePaths, config, presetName);
             displayLintResults(lintResult);
 
             // Record lint metric

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 = 180000;
 
 /**
  * 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 { fetchRemoteConfig } from './remote-config.js';
 import logger from './logger.js';
 
 /**
@@ -157,6 +160,46 @@ export function parseSqlfluffOutput(stdout) {
     return { errors, warnings };
 }
 
+/**
+ * Parse Prettier --check output into structured issues
+ * Prettier outputs [warn] lines for files that need formatting
+ *
+ * @param {string} stdout - Prettier --check stdout
+ * @returns {{ errors: Array, warnings: Array }}
+ */
+export function parsePrettierOutput(stdout) {
+    const errors = [];
+    const warnings = [];
+
+    const lines = stdout.split('\n');
+
+    for (const line of lines) {
+        const trimmed = line.trim();
+
+        // Match [warn] <filepath> lines — skip summary lines
+        const match = trimmed.match(/^\[warn\]\s+(.+)$/);
+        if (!match) continue;
+
+        const content = match[1];
+
+        // Skip Prettier's summary lines (not file paths)
+        if (
+            content.includes('Code style issues') ||
+            content.includes('Forgot to run Prettier')
+        ) {
+            continue;
+        }
+
+        errors.push({
+            file: content,
+            severity: 'error',
+            message: 'File is not properly formatted'
+        });
+    }
+
+    return { errors, warnings };
+}
+
 /**
  * Convert file paths to Spotless-compatible regex pattern
  * Spotless -DspotlessFiles accepts a regex matching absolute file paths
@@ -171,25 +214,94 @@ 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>}
  */
 export const LINTER_TOOLS = {
+    prettier: {
+        name: 'prettier',
+        command: 'npx',
+        args: (files) => ['prettier', '--check', ...files],
+        fixArgs: (files) => ['prettier', '--write', ...files],
+        detectCommand: 'prettier',
+        // 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,
+        timeout: 30000
+    },
     eslint: {
         name: 'eslint',
         command: 'npx',
         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,
@@ -212,7 +324,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: 60000,
+        // 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',
@@ -228,27 +347,63 @@ export const LINTER_TOOLS = {
 };
 
 /**
- * Preset-to-linter mapping
- * Each preset lists the linter tool names it uses
+ * Local fallback preset-to-tool mapping
+ * Used when remote formatters.json is unavailable
  * @type {Object<string, string[]>}
  */
 export const PRESET_LINTERS = {
-    frontend: ['eslint'],
+    frontend: ['prettier', 'eslint'],
     backend: ['spotless'],
-    fullstack: ['eslint', 'spotless'],
+    fullstack: ['prettier', 'eslint', 'spotless'],
     database: ['sqlfluff'],
-    ai: ['eslint'],
-    default: ['eslint']
+    ai: ['prettier', 'eslint'],
+    default: ['prettier', 'eslint']
 };
 
 /**
- * Get linter tool definitions for a preset
+ * Get linter/formatter tool definitions for a preset.
+ * Fetches preset-to-tools mapping from remote config (formatters.json),
+ * falls back to local PRESET_LINTERS when remote is unavailable.
  *
  * @param {string} presetName - Preset name
- * @returns {import('./tool-runner.js').ToolDefinition[]} Tool definitions
+ * @returns {Promise<import('./tool-runner.js').ToolDefinition[]>} Tool definitions
  */
-export function getLinterToolsForPreset(presetName) {
-    const toolNames = PRESET_LINTERS[presetName] || PRESET_LINTERS.default;
+export async function getLinterToolsForPreset(presetName) {
+    // Try remote config first
+    const remoteConfig = await fetchRemoteConfig('formatters.json');
+
+    let toolNames;
+
+    if (remoteConfig?.presetTools?.[presetName]) {
+        toolNames = remoteConfig.presetTools[presetName];
+        logger.debug('linter-runner - getLinterToolsForPreset', 'Using remote preset tools', {
+            preset: presetName,
+            tools: toolNames
+        });
+    } else if (remoteConfig?.presetTools?.default) {
+        toolNames = remoteConfig.presetTools.default;
+        logger.debug('linter-runner - getLinterToolsForPreset',
+            'Preset not in remote config, using remote default', {
+                preset: presetName,
+                tools: toolNames
+            });
+    } else {
+        // Fall back to local
+        toolNames = PRESET_LINTERS[presetName] || PRESET_LINTERS.default;
+        logger.debug('linter-runner - getLinterToolsForPreset', 'Using local fallback', {
+            preset: presetName,
+            tools: toolNames,
+            remoteAvailable: remoteConfig !== null
+        });
+    }
+
+    // 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);
 }
 
@@ -260,12 +415,12 @@ export function getLinterToolsForPreset(presetName) {
  * @param {string} [presetName] - Preset name (default: 'default')
  * @returns {{ results: ToolRunResult[], totalErrors: number, totalWarnings: number, totalFixed: number }}
  */
-export function runLinters(files, config, presetName = 'default') {
+export async function runLinters(files, config, presetName = 'default') {
     const lintConfig = config.linting || {};
     const autoFix = lintConfig.autoFix !== false;
     const timeout = lintConfig.timeout || 30000;
 
-    const tools = getLinterToolsForPreset(presetName);
+    const tools = await getLinterToolsForPreset(presetName);
     const results = [];
 
     logger.debug('linter-runner - runLinters', 'Starting linters', {
@@ -306,14 +461,53 @@ export 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)}`);
+            }
+        }
+
+        const toolOpts = {
             autoFix,
             timeout,
-            restage: true
-        });
+            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 |).
+        if (effectiveToolDef.perFile && matchingFiles.length > 1) {
+            logger.debug('linter-runner - runLinters',
+                `Running ${effectiveToolDef.name} per-file`, { 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
@@ -415,8 +609,8 @@ export function lintIssuesToAnalysisDetails(lintResult) {
  *
  * @param {string} presetName - Preset name
  */
-export function checkLinterAvailability(presetName) {
-    const tools = getLinterToolsForPreset(presetName);
+export async function checkLinterAvailability(presetName) {
+    const tools = await getLinterToolsForPreset(presetName);
 
     if (tools.length === 0) {
         return;

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()) {
@@ -234,13 +470,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 +508,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 +521,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) {
             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 +576,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 +601,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 +612,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,69 +1,73 @@
-{
-    "name": "claude-git-hooks",
-    "version": "2.34.0",
-    "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
-    "type": "module",
-    "bin": {
-        "claude-hooks": "./bin/claude-hooks"
-    },
-    "scripts": {
-        "test": "npm run test:all",
-        "test:all": "npm run lint && npm run test:smoke && npm run test:unit && npm run test:integration",
-        "test:smoke": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/smoke --maxWorkers=1",
-        "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --forceExit",
-        "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration --maxWorkers=1 --testTimeout=30000 --forceExit",
-        "test:integration:ci": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration/ci-safe.test.js --maxWorkers=1 --testTimeout=30000 --forceExit",
-        "test:changed": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --changedSince=main --forceExit",
-        "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
-        "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
-        "lint": "eslint lib/ bin/claude-hooks",
-        "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"
-    },
-    "keywords": [
-        "git",
-        "hooks",
-        "claude",
-        "ai",
-        "code-review",
-        "commit-messages",
-        "pre-commit",
-        "automation"
-    ],
-    "author": "Pablo Rovito",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/mscope-S-L/git-hooks.git"
-    },
-    "engines": {
-        "node": ">=16.9.0"
-    },
-    "engineStrict": false,
-    "os": [
-        "darwin",
-        "linux",
-        "win32"
-    ],
-    "preferGlobal": true,
-    "files": [
-        "bin/",
-        "lib/",
-        "templates/",
-        "README.md",
-        "CHANGELOG.md",
-        "CLAUDE.md",
-        "LICENSE"
-    ],
-    "dependencies": {
-        "@octokit/rest": "^21.0.0"
-    },
-    "devDependencies": {
-        "@types/jest": "^29.5.0",
-        "eslint": "^8.57.1",
-        "jest": "^29.7.0",
-        "prettier": "^3.2.0"
-    }
-}
+{
+    "name": "claude-git-hooks",
+    "version": "2.35.2",
+    "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
+    "type": "module",
+    "bin": {
+        "claude-hooks": "./bin/claude-hooks"
+    },
+    "scripts": {
+        "test": "npm run test:all",
+        "test:all": "npm run lint && npm run test:smoke && npm run test:unit && npm run test:integration",
+        "test:smoke": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/smoke --maxWorkers=1",
+        "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --forceExit",
+        "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration --maxWorkers=1 --testTimeout=30000 --forceExit",
+        "test:integration:ci": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration/ci-safe.test.js --maxWorkers=1 --testTimeout=30000 --forceExit",
+        "test:changed": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --changedSince=main --forceExit",
+        "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+        "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+        "lint": "eslint lib/ bin/claude-hooks",
+        "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",
+        "library:tokens": "node .library/tools/measure-tokens.js",
+        "library:graph": "node .library/tools/generate-graph.js"
+    },
+    "keywords": [
+        "git",
+        "hooks",
+        "claude",
+        "ai",
+        "code-review",
+        "commit-messages",
+        "pre-commit",
+        "automation"
+    ],
+    "author": "Pablo Rovito",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/mscope-S-L/git-hooks.git"
+    },
+    "engines": {
+        "node": ">=16.9.0"
+    },
+    "engineStrict": false,
+    "os": [
+        "darwin",
+        "linux",
+        "win32"
+    ],
+    "preferGlobal": true,
+    "files": [
+        "bin/",
+        "lib/",
+        "templates/",
+        "README.md",
+        "CHANGELOG.md",
+        "CLAUDE.md",
+        "LICENSE"
+    ],
+    "dependencies": {
+        "@octokit/rest": "^21.0.0"
+    },
+    "devDependencies": {
+        "@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"
+    }
+}