Claude Code Hooks: Chặn Lệnh Xóa Nguy Hiểm trước khi Agent Chạy

Ba hiểu lầm làm hook "chặn" mà không chặn

Trước khi viết dòng code nào, mình muốn gỡ ba hiểu lầm mà tài liệu cho thấy là dễ mắc nhất, vì chính chúng làm một hook trông như đang chặn mà thực ra không chặn gì:

• Tưởng: exit 1 là chặnThực tế: chỉ exit 2 mới chặn. Script "báo lỗi" theo thói quen Unix (exit 1) để lệnh chạy tiếp.
• Tưởng: hook treo thì lệnh dừngThực tế: hook bị timeout cũng không chặn; lệnh đi tiếp qua luồng xin quyền bình thường.
• Tưởng: hook trả allow là xongThực tế: allow không thắng được luật deny bạn đã đặt trong phần quyền.

Chặn rm đệ quy trong 3 bước

Giờ đến phần làm thật. Mỗi lần agent gọi công cụ, Claude Code gửi thông tin về lần gọi đó vào stdin của hook dưới dạng JSON; với công cụ Bash, lệnh sắp chạy nằm ở tool_input.command. Cả bộ chặn của mình chỉ xoay quanh việc đọc trường đó.

1. Bước 1: khai báo hook trong settings.json

   Vì sao cần bước này: Claude Code chỉ chạy hook khi bạn ghi nó vào file cài đặt, giống việc dán tờ nội quy lên cổng thì người gác mới biết phải kiểm gì.

   Làm ở đâu: trong thư mục dự án, mở (hoặc tạo) thư mục .claude, rồi tạo file settings.json bằng trình soạn thảo bạn quen, như VS Code hay Notepad. Dán nguyên đoạn dưới vào và lưu lại. Nói bằng lời thường, đoạn này bảo Claude Code: trước mỗi lệnh Bash hoặc PowerShell, hãy chạy script chan-xoa.mjs bằng Node; script hỏng thì cũng chặn luôn.

   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Bash|PowerShell",
           "hooks": [
             {
               "type": "command",
               "command": "node",
               "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/chan-xoa.mjs"],
               "onFailure": "block"
             }
           ]
         }
       ]
     }
   }

   • args bật dạng exec: Claude Code gọi thẳng node với đường dẫn script, không qua shell, nên đường dẫn có dấu cách vẫn đúng. Tài liệu khuyên dùng dạng này khi có biến đường dẫn như ${CLAUDE_PROJECT_DIR}.
   • onFailure: "block" làm hook bị lỗi hay treo cũng tính là chặn. Thiếu nó, một script gõ sai đường dẫn sẽ âm thầm cho mọi lệnh đi qua.

2. Bước 2: viết script chặn bằng Node

   Vì sao cần bước này: file ở bước 1 mới chỉ nói "hãy gọi người gác"; script này chính là người gác, quyết định lệnh nào bị chặn.

   Làm ở đâu: trong thư mục .claude vừa tạo, tạo thêm thư mục hooks, rồi tạo file chan-xoa.mjs và dán đoạn dưới vào. Máy cần cài sẵn Node.js để chạy file này. Nói gọn, script đọc lệnh Claude sắp chạy, nếu thấy đó là lệnh xóa cả thư mục thì in lý do và trả mã 2 để chặn; mọi lệnh khác nó để yên.

   let raw = '';
   for await (const chunk of process.stdin) raw += chunk;
   const cmd = JSON.parse(raw).tool_input?.command ?? '';
   // rm kèm cờ đệ quy ở bất kỳ vị trí nào: -r, -R, -rf, -fr, -r -f, --recursive
   const rmDeQuy = /\brm\b[^;&|\n]*\s(-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)\b/;
   // PowerShell: Remove-Item (hoặc alias ri, del, rd, rmdir) kèm -Recurse
   const psDeQuy = /\b(Remove-Item|ri|del|rd|rmdir)\b[^;\n]*-Recurse/i;
   if (rmDeQuy.test(cmd) || psDeQuy.test(cmd)) {
     console.error('Lệnh xóa đệ quy bị chặn. Hãy xóa từng file cụ thể.');
     process.exit(2);
   }

   Thoát mã 2 nghĩa là chặn: lệnh không chạy, và nội dung stderr được gửi cho Claude để nó biết lý do và đổi cách làm. Thoát mã 0 mà không in gì nghĩa là hook không có ý kiến, lệnh đi tiếp qua luồng xin quyền như thường. Im lặng không phải là duyệt.

   Mình chọn viết script bằng Node thay vì Bash để nó chạy giống nhau trên Windows, macOS và Linux, miễn là máy có Node. Ví dụ Bash trong tài liệu chính thức thì cần cài thêm jq.

3. Bước 3: thử với 12 cách viết của cùng một lệnh

   Vì sao cần bước này: một người gác chưa từng diễn tập rất dễ để lọt người. Thử với nhiều cách viết của cùng một lệnh là cách duy nhất biết hook chặn thật hay không.

   Viết xong, mình chạy thử script với 12 lệnh mẫu trên Node 24:

   Kết quả	Lệnh
   Bị chặn	rm -rf, rm -fr, rm -Rf, rm -r -f, rm --recursive --force, sudo rm -rf /, cd a && rm -rf b, Remove-Item -Recurse -Force
   Cho qua	ls -la, rm -f file.txt, git rm --cached, Remove-Item a.txt

   Ảnh chụp thật

   Bản đầu tiên mình viết chỉ dò -rf và -fr liền nhau, nên để lọt rm -r -f và rm --recursive. Mình chỉ phát hiện ra nhờ bước thử này, và đó cũng là lý do mình khuyên bạn tự thử hook với nhiều cách viết của cùng một lệnh.

Công cụ dựng sẵn trong Skills hub

Nếu bạn không muốn tự viết từ đầu, mình đã ghi lại hai công cụ dựng sẵn trong Skills hub:

• destructive-command-guard là bộ chặn lệnh nguy hiểm viết sẵn, nhiều mẫu hơn ví dụ ở trên. Trang hub ghi lại hai điều cần biết trước khi cài: giấy phép có hạn chế riêng, và có báo cáo Windows Defender chặn file chạy của nó.
• tdd-guard dùng hook để chặn agent viết code khi chưa có test thất bại. Nó gọi thêm model để kiểm tra mỗi lần sửa, nên tốn thêm token; một phép đo độc lập không thấy code tốt hơn.

Ngoài việc chặn lệnh, hook còn giúp tiết kiệm token: tài liệu chi phí có ví dụ hook PreToolUse sửa lệnh chạy test để chỉ in ra phần thất bại. Xem thêm trong bài tiết kiệm token Claude Code.