feat: add Windows path normalization hook (bug #7918 workaround) (#176)

* feat: add PowerShell guidance hook for Windows users

Adds a PreToolUse hook that intercepts Linux/bash commands on Windows and either:
- Auto-converts simple commands to PowerShell equivalents (cat→Get-Content, rm→Remove-Item, etc.)
- Rejects complex commands with clear PowerShell syntax examples

This reduces trial-and-error when Claude tries Linux commands that fail on Windows.

Features:
- 15+ auto-conversions for common commands (cat, rm, cp, mv, mkdir, touch, head, tail, etc.)
- 20+ rejection patterns with detailed PowerShell alternatives (grep, sed, awk, chmod, etc.)
- Only runs on Windows and only when explicitly enabled in config
- Passes through PowerShell cmdlets unchanged
- 42 tests covering all functionality

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: guard main() with import.meta.main check

Prevents hook from executing when imported for testing,
matching pattern used by other hooks in the codebase.

Addresses Codex P1 review feedback.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: use ESM import for dirname instead of require

The require('node:path') call inside isHookEnabled() throws in ESM
packages since require is undefined, causing the hook to always
return false and never execute.

Addresses second Codex P1 review feedback.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: add file path normalization to Windows hook

Extends the PowerShell guidance hook to also normalize file paths
in Edit, Write, Read, and MultiEdit tools on Windows. Converts
forward slashes to backslashes, working around Claude Code bug #7918
where the Edit tool fails with "File has been unexpectedly modified"
when paths use forward slashes on Windows.

Changes:
- Hook now intercepts file tools in addition to Bash
- Paths with forward slashes are converted to backslashes
- Added 7 new tests for path normalization scenarios
- Updated setup documentation to explain both features

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: use correct Claude Code hook output format for PreToolUse

The hook was using an incorrect JSON output format. Claude Code
expects hookSpecificOutput with hookEventName, permissionDecision,
and updatedInput fields for PreToolUse hooks that modify tool input.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: simplify hook to path normalization only

Remove command conversion logic since Git Bash provides Unix commands
that work fine on Windows. Keep only the path normalization feature
that works around Claude Code bug #7918.

- Remove SIMPLE_CONVERSIONS and REJECTION_PATTERNS
- Remove bash command interception
- Keep file path normalization for Edit/Write/Read/MultiEdit tools
- Update tests to match simplified functionality

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: rename hook to windows-path-normalization

Rename from powershell-guidance since the hook now only handles
path normalization, not PowerShell command conversion.

- Rename files: powershell-guidance.ts → windows-path-normalization.ts
- Update function name: powershellGuidanceHook → windowsPathNormalizationHook
- Update config key: powershell_guidance → windows_path_normalization
- Remove Bash from hook matcher (no longer needed)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Craig Haseler <cahaseler@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: cahaseler

.cc-track/track.config.json

@@ -37,6 +37,10 @@
     "pre_tool_validation": {
       "enabled": true,
       "description": "Pre-tool validation for task files and branch protection"
+    },
+    "windows_path_normalization": {
+      "enabled": true,
+      "description": "Windows only: normalizes file paths to backslashes (workaround for Claude Code bug #7918). Must be explicitly enabled."
     }
   },
   "git": {

commands/setup-cc-track.md

@@ -175,6 +175,18 @@ Present feature options and let user choose what to enable:
   - ⚠️ Cons: Adds validation overhead to every web search operation
   - Ask: "Enable web search validation? (helps prevent unnecessary searches)"
 
+**Windows Only:**
+- `powershell_guidance` - Windows compatibility hook with two functions:
+  1. **Command conversion:** Auto-converts simple Linux commands (cat, rm, cp, mv, head, tail, etc.) to PowerShell
+  2. **Path normalization:** Converts forward slashes to backslashes in file operations (workaround for Claude Code #7918)
+  - ✅ Pros: Auto-converts simple Linux commands to PowerShell equivalents
+  - ✅ Pros: Rejects complex commands with clear PowerShell alternatives and syntax examples
+  - ✅ Pros: Prevents trial-and-error when Claude tries Linux commands that fail on Windows
+  - ✅ Pros: Fixes "File has been unexpectedly modified" errors on Windows (Claude Code bug #7918)
+  - ⚠️ Only useful on Windows - do NOT enable on macOS/Linux
+  - Ask: (only if on Windows) "Enable Windows compatibility hook? (fixes path issues, auto-converts Linux commands)"
+  - Note: This is a PreToolUse hook that intercepts Bash, Edit, Write, Read, and MultiEdit tools
+
 ### 4. Configuration File Creation
 
 Based on user selections, create `.cc-track/track.config.json`:
@@ -196,6 +208,9 @@ Read the template from `${CLAUDE_PLUGIN_ROOT}/templates/track.config.json` and c
     },
     "pre_tool_validation": {
       "enabled": true/false
+    },
+    "powershell_guidance": {
+      "enabled": true/false
     }
   },
   "features": {
@@ -317,10 +332,14 @@ Based on enabled features, configure hooks in Claude Code settings.
 Show user what hooks will be enabled:
 - `edit_validation` → PostToolUse hook
 - `pre_tool_validation` → PreToolUse hook
+- `powershell_guidance` → PreToolUse hook (Windows only)
 
 Explain:
 - Hooks execute TypeScript files from `${CLAUDE_PLUGIN_ROOT}/hooks/`
 - User can disable individual hooks via `/config-track` later
+- The `powershell_guidance` hook intercepts Bash/Edit/Write/Read tools to:
+  - Convert Linux commands to PowerShell or provide guidance
+  - Normalize file paths to Windows backslash format (fixes Claude Code bug #7918)
 
 ### 8. Configure Claude Code Settings (if statusline enabled)
 

hooks/hooks.json

@@ -11,6 +11,11 @@
       "name": "pre-tool-validation",
       "script": "bun run ${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-validation.ts",
       "description": "Validates branch protection and task file integrity before tool use"
+    },
+    {
+      "name": "powershell-guidance",
+      "script": "bun run ${CLAUDE_PLUGIN_ROOT}/hooks/powershell-guidance.ts",
+      "description": "Windows only: Converts Linux commands to PowerShell or provides guidance"
     }
   ]
 }

hooks/windows-path-normalization.test.ts

@@ -0,0 +1,167 @@
+// ABOUTME: Tests for the Windows path normalization hook
+// ABOUTME: Verifies path normalization for Windows (Claude Code bug #7918 workaround)
+
+import { describe, expect, test } from 'bun:test';
+import { windowsPathNormalizationHook } from './windows-path-normalization';
+
+describe('windowsPathNormalizationHook', () => {
+  const mockEnabled = () => true;
+  const mockDisabled = () => false;
+
+  describe('platform detection', () => {
+    test('approves all tools on non-Windows platforms', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'Edit', tool_input: { file_path: 'D:/test/file.ts' } },
+        { isEnabled: mockEnabled, platform: 'linux' },
+      );
+
+      expect(result.decision).toBe('approve');
+    });
+
+    test('approves all tools on macOS', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'Edit', tool_input: { file_path: '/home/user/file.ts' } },
+        { isEnabled: mockEnabled, platform: 'darwin' },
+      );
+
+      expect(result.decision).toBe('approve');
+    });
+  });
+
+  describe('config check', () => {
+    test('approves all tools when hook is disabled', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'Edit', tool_input: { file_path: 'D:/test/file.ts' } },
+        { isEnabled: mockDisabled, platform: 'win32' },
+      );
+
+      expect(result.decision).toBe('approve');
+    });
+  });
+
+  describe('file path normalization (workaround for Claude Code #7918)', () => {
+    test('normalizes forward slashes to backslashes in Edit tool', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'Edit', tool_input: { file_path: 'D:/repos/project/file.ts', old_string: 'a', new_string: 'b' } },
+        { isEnabled: mockEnabled, platform: 'win32' },
+      );
+
+      expect(result.decision).toBe('modify');
+      expect(result.modified_tool_input?.file_path).toBe('D:\\repos\\project\\file.ts');
+      expect(result.modified_tool_input?.old_string).toBe('a');
+    });
+
+    test('normalizes forward slashes in Write tool', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'Write', tool_input: { file_path: 'C:/Users/test/file.txt', content: 'hello' } },
+        { isEnabled: mockEnabled, platform: 'win32' },
+      );
+
+      expect(result.decision).toBe('modify');
+      expect(result.modified_tool_input?.file_path).toBe('C:\\Users\\test\\file.txt');
+      expect(result.modified_tool_input?.content).toBe('hello');
+    });
+
+    test('normalizes forward slashes in Read tool', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'Read', tool_input: { file_path: 'D:/Development/pars/cc-track/src/index.ts' } },
+        { isEnabled: mockEnabled, platform: 'win32' },
+      );
+
+      expect(result.decision).toBe('modify');
+      expect(result.modified_tool_input?.file_path).toBe('D:\\Development\\pars\\cc-track\\src\\index.ts');
+    });
+
+    test('normalizes forward slashes in MultiEdit tool', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'MultiEdit', tool_input: { file_path: 'src/lib/config.ts', edits: [] } },
+        { isEnabled: mockEnabled, platform: 'win32' },
+      );
+
+      expect(result.decision).toBe('modify');
+      expect(result.modified_tool_input?.file_path).toBe('src\\lib\\config.ts');
+    });
+
+    test('approves file tools that already use backslashes', async () => {
+      const result = await windowsPathNormalizationHook(
+        {
+          tool_name: 'Edit',
+          tool_input: { file_path: 'D:\\repos\\project\\file.ts', old_string: 'a', new_string: 'b' },
+        },
+        { isEnabled: mockEnabled, platform: 'win32' },
+      );
+
+      expect(result.decision).toBe('approve');
+    });
+
+    test('does not normalize paths on non-Windows platforms', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'Edit', tool_input: { file_path: '/home/user/file.ts', old_string: 'a', new_string: 'b' } },
+        { isEnabled: mockEnabled, platform: 'linux' },
+      );
+
+      expect(result.decision).toBe('approve');
+    });
+
+    test('does not normalize paths when hook is disabled', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'Edit', tool_input: { file_path: 'D:/repos/file.ts', old_string: 'a', new_string: 'b' } },
+        { isEnabled: mockDisabled, platform: 'win32' },
+      );
+
+      expect(result.decision).toBe('approve');
+    });
+  });
+
+  describe('tool filtering', () => {
+    test('approves non-file tools', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'Grep', tool_input: { pattern: 'test' } },
+        { isEnabled: mockEnabled, platform: 'win32' },
+      );
+
+      expect(result.decision).toBe('approve');
+    });
+
+    test('approves Bash tool (no command conversion)', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'Bash', tool_input: { command: 'cat file.txt' } },
+        { isEnabled: mockEnabled, platform: 'win32' },
+      );
+
+      expect(result.decision).toBe('approve');
+    });
+
+    test('approves file tools without file_path', async () => {
+      const result = await windowsPathNormalizationHook(
+        { tool_name: 'Edit', tool_input: { other: 'value' } },
+        { isEnabled: mockEnabled, platform: 'win32' },
+      );
+
+      expect(result.decision).toBe('approve');
+    });
+  });
+
+  describe('preserves other tool_input properties', () => {
+    test('preserves all properties in modified output', async () => {
+      const result = await windowsPathNormalizationHook(
+        {
+          tool_name: 'Edit',
+          tool_input: {
+            file_path: 'D:/test/file.ts',
+            old_string: 'foo',
+            new_string: 'bar',
+            replace_all: true,
+          },
+        },
+        { isEnabled: mockEnabled, platform: 'win32' },
+      );
+
+      expect(result.decision).toBe('modify');
+      expect(result.modified_tool_input?.file_path).toBe('D:\\test\\file.ts');
+      expect(result.modified_tool_input?.old_string).toBe('foo');
+      expect(result.modified_tool_input?.new_string).toBe('bar');
+      expect(result.modified_tool_input?.replace_all).toBe(true);
+    });
+  });
+});

hooks/windows-path-normalization.ts

@@ -0,0 +1,157 @@
+// ABOUTME: PreToolUse hook for Windows that normalizes file paths to backslash format
+// ABOUTME: Works around Claude Code bug #7918 where Edit fails with forward slashes
+// ABOUTME: Only active when explicitly enabled in track.config.json
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { join } from 'node:path/posix';
+import { createLogger } from '../skills/cc-track-tools/lib/logger';
+
+const logger = createLogger('windows-path-normalization');
+
+interface HookInput {
+  tool_name: string;
+  tool_input: {
+    file_path?: string;
+    [key: string]: unknown;
+  };
+}
+
+interface HookResult {
+  decision: 'block' | 'approve' | 'modify';
+  reason?: string;
+  modified_tool_input?: {
+    file_path?: string;
+    [key: string]: unknown;
+  };
+}
+
+// File tools that use file_path parameter
+const FILE_TOOLS = ['Edit', 'Write', 'Read', 'MultiEdit'];
+
+// Load config to check if hook is enabled
+function isHookEnabled(): boolean {
+  try {
+    // Look for track.config.json in current directory or parents
+    let searchPath = process.cwd();
+
+    while (true) {
+      const configPath = join(searchPath, '.cc-track', 'track.config.json');
+      if (existsSync(configPath)) {
+        const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+        return config?.hooks?.windows_path_normalization?.enabled === true;
+      }
+
+      const parentPath = dirname(searchPath);
+      if (parentPath === searchPath) break;
+      searchPath = parentPath;
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// Main hook function
+export async function windowsPathNormalizationHook(
+  input: HookInput,
+  deps: {
+    isEnabled?: () => boolean;
+    platform?: string;
+  } = {},
+): Promise<HookResult> {
+  const isEnabled = deps.isEnabled || isHookEnabled;
+  const platform = deps.platform || process.platform;
+
+  // Only run on Windows
+  if (platform !== 'win32') {
+    return { decision: 'approve' };
+  }
+
+  // Only run if explicitly enabled
+  if (!isEnabled()) {
+    return { decision: 'approve' };
+  }
+
+  // Handle file tools - normalize paths to backslashes on Windows
+  // This works around Claude Code bug #7918 where Edit fails with forward slashes
+  if (FILE_TOOLS.includes(input.tool_name)) {
+    const filePath = input.tool_input.file_path;
+    if (filePath && typeof filePath === 'string' && filePath.includes('/')) {
+      const normalizedPath = filePath.replace(/\//g, '\\');
+      logger.info('Normalizing file path to Windows format', {
+        original: filePath,
+        normalized: normalizedPath,
+        tool: input.tool_name,
+      });
+      return {
+        decision: 'modify',
+        reason: `Normalized path separators to Windows format (workaround for Claude Code #7918)`,
+        modified_tool_input: {
+          ...input.tool_input,
+          file_path: normalizedPath,
+        },
+      };
+    }
+  }
+
+  // No changes needed
+  return { decision: 'approve' };
+}
+
+// CLI entry point for Claude Code hook system
+async function main() {
+  try {
+    const input = await new Promise<string>((resolve) => {
+      let data = '';
+      process.stdin.on('data', (chunk) => {
+        data += chunk;
+      });
+      process.stdin.on('end', () => {
+        resolve(data);
+      });
+    });
+
+    const hookInput: HookInput = JSON.parse(input);
+    const result = await windowsPathNormalizationHook(hookInput);
+
+    if (result.decision === 'block') {
+      // Output in Claude Code's expected format for blocking
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: result.reason,
+          },
+        }),
+      );
+      process.exit(2); // Exit code 2 = block
+    } else if (result.decision === 'modify') {
+      // Output in Claude Code's expected format for modifying tool input
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'allow',
+            updatedInput: result.modified_tool_input,
+          },
+        }),
+      );
+      process.exit(0);
+    } else {
+      // Approve - just exit cleanly
+      process.exit(0);
+    }
+  } catch (error) {
+    logger.error('Hook error', { error });
+    // On error, don't block - let the command through
+    process.exit(0);
+  }
+}
+
+// CLI entrypoint - only run when executed directly, not when imported
+if (import.meta.main) {
+  main();
+}