Symlink Hook Execution Failure in Claude Code

Bug Description
⏺ Bug Report: Claude Code Hooks Fail to Execute Through Symlinks

Issue: Claude Code hooks silently fail or hang indefinitely when configured to execute through symlinked directories.

Reproduction Steps:

1. Create hooks in a project directory (e.g., /Users/user/projects/my-hooks/)
2. Create a symlink: ln -s /Users/user/projects/my-hooks ~/.claude/hooks
3. Configure ~/.claude/settings.json with hook paths like ~/.claude/hooks/pre_tool_use.py
4. Attempt to use Claude Code - hooks will hang or fail silently

Expected Behavior: Hooks should execute normally through symlinks, as symlinks work for other file operations (reading, listing).

Actual Behavior: Hook execution hangs indefinitely or fails silently. No error messages are provided.

Workaround: Use absolute paths directly to the hook files instead of symlink paths:

• ❌ ~/.claude/hooks/pre_tool_use.py (through symlink)
• ✅ /Users/user/projects/my-hooks/pre_tool_use.py (direct path)

Impact: This caused hours of unnecessary debugging, as the issue appeared to be with the hook code itself rather than the execution path. The symlink appears to work for file operations (ls, cat) but not for execution.

Environment: macOS, Claude Code with Python hooks

Environment Info

• Platform: darwin
• Terminal: vscode
• Version: 1.0.72
• Feedback ID: f1710d3d-8c74-45aa-845e-9883b8bd00ba

Note: Not sure the errors below are relevant. And I think I understand the first one. While refactoring agents for me, claude put documenation files in the agents folder. I'll go move those.
Errors

[{"error":"Error: Agent file /Users/bpruss/repos/cdc/cdc-devtools/.claude/agents/DEVOPS_CONSOLIDATION_POC.md is missing required 'name' in frontmatter\n    at OY8 (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:1812)\n    at file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:333\n    at Array.map (<anonymous>)\n    at file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:269\n    at async file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:112\n    at async VuB (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:3056:4)\n    at async Object.prompt (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:3128:1219)\n    at async DRB (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:1733:191)\n    at async Promise.all (index 0)\n    at async Promise.all (index 0)","timestamp":"2025-08-09T03:39:39.593Z"},{"error":"Error: Agent file /Users/bpruss/repos/cdc/cdc-devtools/.claude/agents/AGENT_REGISTRY.md is missing required 'name' in frontmatter\n    at OY8 (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:1812)\n    at file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:333\n    at Array.map (<anonymous>)\n    at file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:269\n    at async file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:112\n    at async VuB (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:3056:4)\n    at async Object.prompt (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:3128:1219)\n    at async DRB (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:1733:191)\n    at async Promise.all (index 0)\n    at async Promise.all (index 0)","timestamp":"2025-08-09T03:39:39.596Z"},{"error":"Error: Agent file /Users/bpruss/repos/cdc/cdc-devtools/.claude/agents/README.md is missing required 'name' in frontmatter\n    at OY8 (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:1812)\n    at file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:333\n    at Array.map (<anonymous>)\n    at file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:269\n    at async file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:112\n    at async VuB (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:3056:4)\n    at async Object.prompt (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:3128:1219)\n    at async DRB (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:1733:191)\n    at async Promise.all (index 0)\n    at async Promise.all (index 0)","timestamp":"2025-08-09T03:39:39.597Z"},{"error":"Error: Agent file /Users/bpruss/repos/cdc/cdc-devtools/.claude/agents/NAMING_CONVENTION.md is missing required 'name' in frontmatter\n    at OY8 (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:1812)\n    at file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:333\n    at Array.map (<anonymous>)\n    at file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:269\n    at async file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:2213:112\n    at async VuB (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:3056:4)\n    at async Object.prompt (file:///opt/home

Note: Error logs were truncated.