Bug Description

The PreToolUse Write hook that blocks .md file creation is too aggressive. It blocks all .md files except README.md, CLAUDE.md, AGENTS.md, and CONTRIBUTING.md, even when the user explicitly asks Claude to create documentation files in their project's docs/ directory.

Hook in question

From hooks/hooks.json (line ~36-44):

{
  "matcher": "Write",
  "hooks": [
    {
      "type": "command",
      "command": "node -e \"...if(/\\.(md|txt)$/.test(p)&&!/(README|CLAUDE|AGENTS|CONTRIBUTING)\\.md$/.test(p)&&!/\\.claude\\/plans\\//.test(p)){console.error('[Hook] BLOCKED: Unnecessary documentation file creation');...process.exit(2)}\""
    }
  ],
  "description": "Block creation of random .md files - keeps docs consolidated"
}

Reproduction

1. Have a project with a docs/ directory (e.g., docs/experiments/, docs/reports/)
2. Ask Claude to create a report file like docs/MODEL_COMPARISON.md
3. The Write tool is blocked with:

   [Hook] BLOCKED: Unnecessary documentation file creation
   [Hook] File: /home/user/project/docs/MODEL_COMPARISON.md
   [Hook] Use README.md for documentation instead
   

Impact

This blocks legitimate use cases:

• Writing experiment reports (docs/experiments/exp-1-report.md)
• Creating architecture docs (docs/ARCHITECTURE.md)
• Project-specific documentation in docs/ directories
• Any .md or .txt file that isn't one of the 4 allowed names

The workaround is to use Bash with cat > heredoc instead of the Write tool, which defeats the purpose of the hook (keeping things clean) and makes Claude use a worse tool for the job.

Suggested Fix

Allow .md files in docs/ directories, or make the allowlist configurable. For example:

// Allow files in docs/ directories
if (/\/docs\//.test(p)) { /* allow */ }

// Or allow any .md file the user explicitly requested
// (hard to detect, but at least don't block docs/ paths)

Alternatively, make this hook opt-in rather than default, since many projects have legitimate docs/ directories with multiple markdown files.

Environment

• Claude Code CLI
• everything-claude-code plugin v1.4.1
• Linux