[BUG] Breaking change: FileChange hook removed without migration guide or deprecation notice

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

The FileChange hook event type was removed in a recent version without:

1. Deprecation notice in prior releases
2. Migration guide in documentation
3. Clear explanation of alternatives

This is a breaking change that silently breaks existing automation workflows.

Evidence of Breaking Change

Git history proves FileChange existed:

Original working format (commit 0cdd488):

{
  "hooks": [
    {
      "id": "contract-sync-file-watch",
      "event": "FileChange",
      "matches": [
        "Sources/APIClient/**/*.swift",
        "Sources/APIClientLive/**",
        "Sources/SharedModels/**/*.swift"
      ],
      "run": "agent:contract-sync",
      "debounce_seconds": 90
    }
  ]
}

Current /Doctor error:

Valid values: "PreToolUse", "PostToolUse", "Notification", "UserPromptSubmit", 
"SessionStart", "SessionEnd", "Stop", "SubagentStop", "PreCompact"

Hooks use a new format with matchers...

FileChange is not in the list of valid events anymore.

Impact

What breaks:

• File-watching automation that triggers on specific file pattern changes
• Developer workflows that auto-verify contract sync when API client files change
• Any hooks configuration that used FileChange event type

Specific use case that broke:
We had automation that watched API client files (Sources/APIClient/**/*.swift) and automatically triggered contract verification when they changed. This provided:

• Real-time feedback (90-second debounced checks)
• Catch API/client drift before PR submission
• Prevent pushing broken contract changes to CI

Without FileChange, we lose local pre-commit verification and only catch issues in CI after pushing.

What Should Happen?

Option 1: Restore FileChange (preferred)

• Re-add FileChange as a valid hook event
• Document it properly in hooks reference

Option 2: Provide clear migration path

• Document why FileChange was removed
• Provide idiomatic replacement using PostToolUse or other events
• Explain limitations of alternatives (e.g., PostToolUse can't filter by file patterns in matchers)
• Show migration examples

Option 3: Better breaking change communication

• Add deprecation warnings before removing features
• Include migration guides in changelogs
• Update /Doctor to suggest alternatives, not just list valid values

Error Messages/Logs

/Doctor output:

Valid values: "PreToolUse", "PostToolUse", "Notification", "UserPromptSubmit", 
"SessionStart", "SessionEnd", "Stop", "SubagentStop", "PreCompact"

Learn more: https://docs.claude.com/en/docs/claude-code/hooks

Hooks use a new format with matchers. Example: {"PostToolUse": [{"matcher": {"tools": ["BashTool"]}, "hooks": [{"type": "command", "command": "echo Done"}]}]}

Steps to Reproduce

1. Check out commit 0cdd488 (or any commit where FileChange hooks worked)
2. Update to latest Claude Code version
3. Run /Doctor
4. Observe that FileChange is no longer a valid hook event
5. Existing hooks configuration fails validation

Claude Model

N/A - This is a hooks system issue, not model-related

Is this a regression?

Yes, this worked in a previous version

Last Working Version

Unknown - need to investigate which version removed FileChange

Claude Code Version

Latest (v2.0.37+)

Platform

N/A - Affects all platforms

Operating System

Linux (WSL2)

Terminal/Shell

Bash

Additional Information

Questions for maintainers:

1. Why was FileChange removed? Was it a technical limitation, performance issue, or design decision?

1. What's the intended replacement? The docs don't mention how to achieve file-watching behavior with the new hooks format.

1. Can PostToolUse match file patterns? The new format seems to only support tool name matching, not file glob patterns:

``json
{
"PostToolUse": [{
"matcher": {"tools": ["Edit"]}, // Can this filter by file path?
"hooks": [...]
}]
}
``

1. Will FileChange be restored? Or should we build external file watchers and abandon the hooks system for this use case?

Community impact:
This likely affects many users who built automation around file-watching hooks. A clear migration guide would help the community adapt without breaking workflows.

Related documentation:

• Hooks reference - No mention of FileChange or migration
• Hooks guide - No migration guide for removed features

---

Request: Please either restore FileChange or provide a clear, documented migration path with examples. Breaking changes need better communication and migration support.