Giải thích hook trong Claude Code: mọi sự kiện và công dụng của chúng

01Cấu trúc của một hook

Cấu hình hook gồm ba cấp:

1. Hook event, ví dụ PreToolUse hoặc Stop.
2. Matcher group, dùng để lọc khi nào hook được kích hoạt, ví dụ "chỉ với tool Bash".
3. Một hoặc nhiều hook handler, tức thứ thực sự được chạy.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

Ví dụ này chạy một script lint sau khi Claude ghi hoặc sửa file. Để thêm event thứ hai, hãy thêm một key ngang hàng trong cùng object hooks.

02Hook nằm ở đâu

Hook từ các file khác nhau được cộng dồn chứ không ghi đè nhau. Gõ /hooks trong Claude Code để xem mọi hook đang hoạt động và nguồn gốc của chúng.

Trong phiên tương tác, Claude Code sẽ tạm giữ các hook, kể cả hook của chính bạn, cho đến khi bạn chấp nhận hộp thoại workspace trust cho thư mục đó.

03Các loại handler

Phần lớn hook là "type": "command", tức chạy một lệnh shell. Ngoài ra còn bốn loại khác:

• http: POST JSON của event tới một URL và đọc response body.
• mcp_tool: gọi một tool trên MCP server mà bạn đã cấu hình.
• prompt: hỏi model Claude một câu hỏi single-turn và đọc quyết định dạng JSON.
• agent: khởi chạy một subagent có thể đọc file trước khi quyết định (thử nghiệm).

Command hook chạy với toàn bộ quyền của user, thông qua sh -c trên macOS và Linux, và Git Bash (hoặc PowerShell) trên Windows. Thêm "async": true để chạy hook ở chế độ nền; khi đó nó không thể đưa ra quyết định nữa.

04Matcher

matcher quyết định những lần xảy ra nào của event sẽ chạy hook. Giá trị được so khớp tùy theo event: tên tool với các tool event, loại thông báo với Notification, cách phiên bắt đầu với SessionStart, v.v.

• "*", "" hoặc không có matcher đều khớp với mọi thứ.
• Chữ cái, chữ số, _, -, dấu cách, | và , được hiểu là tên chính xác. Edit|Write khớp với một trong hai tool.
• Mọi giá trị khác được coi là regular expression của JavaScript, nên mcp__memory__.* khớp với mọi tool của một MCP server.

Matcher phân biệt hoa thường. Một số event, bao gồm Stop và UserPromptSubmit, bỏ qua matcher. Với các tool event, trường if chứa một permission rule như "Bash(git *)" giúp thu hẹp phạm vi của từng handler hơn nữa.

05Input: hook của bạn nhận được gì

Mọi hook đều nhận JSON qua stdin với một số trường chung, gồm session_id, transcript_path, cwd và hook_event_name, cùng các trường riêng của từng event. Ví dụ, hook PreToolUse cho một lệnh Bash sẽ nhận thêm tool_name và tool_input.command. Đọc dữ liệu bằng jq hoặc bất kỳ JSON parser nào:

#!/bin/bash
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")
echo "Claude wants to run: $cmd" >> ~/claude-commands.log
exit 0

06Output: exit code và JSON

Hook phản hồi lại theo một trong hai cách.

Exit code. 0 là thành công. 2 là lỗi chặn: với các event có thể chặn, hành động sẽ dừng lại và nội dung stderr của bạn trở thành lý do. Mọi code khác, kể cả 1 quen thuộc, đều là lỗi không chặn, nên hành động vẫn tiếp tục và bạn chỉ thấy thông báo lỗi hook. Nếu hook dùng để áp đặt một quy tắc, hãy exit 2, đừng dùng 1.

JSON trên stdout. Exit 0 và in ra một object JSON duy nhất để kiểm soát chi tiết hơn. Một số field dùng được ở mọi nơi, ví dụ continue: false để dừng hẳn Claude. Số khác thì tùy event: Stop dùng decision: "block" kèm reason, còn PreToolUse và PermissionRequest đặt quyết định bên trong hookSpecificOutput. Đừng in gì khác ra stdout: chỉ một dòng thừa từ shell profile cũng khiến Claude Code không đọc được JSON.

07Tất cả hook event

Anthropic thỉnh thoảng bổ sung event mới, nên hãy xem tài liệu tham khảo về hook để biết danh sách hiện tại và các trường input của từng event.

08Những event quan trọng cho thông báo

Bốn event sau gần như bao quát mọi thứ bạn muốn được báo:

• Stop cho "Claude đã xong". Xem hướng dẫn về Stop hook.
• Notification cho "Claude đang chờ bạn", với các loại như permission_prompt và idle_prompt. Xem hướng dẫn về Notification hook.
• PermissionRequest để được báo, hoặc trả lời, ngay khi cần cấp quyền. Xem hướng dẫn về PermissionRequest.
• PreToolUse trên tool AskUserQuestion, để xem hoặc trả lời các câu hỏi trắc nghiệm của Claude. Xem trả lời câu hỏi từ điện thoại.

Nếu muốn có sẵn cấu hình desktop để dán vào, hãy bắt đầu với cách nhận thông báo khi Claude Code chạy xong.

09Claude Code Notifier nằm ở đâu trong bức tranh này

Claude Code Notifier được xây dựng hoàn toàn dựa trên các hook này. Công cụ dòng lệnh miễn phí của nó, ccn, chạy trên Mac, Windows và Linux. Khi cài đặt, nó thêm bảy hook vào ~/.claude/settings.json, mỗi hook chạy ccn hook, và tạo một bản sao lưu file một lần. ccn chỉ chạy vài mili giây cho mỗi event rồi thoát, nên không có gì chạy nền cả.

Khi dùng riêng, nó hiển thị thông báo trên desktop. Khi ghép nối với app iPhone hoặc Android, chính các hook đó sẽ gửi câu trả lời của bạn ngược lại: cho phép hoặc từ chối quyền, trả lời câu hỏi, hoặc gửi chỉ dẫn tiếp theo sau khi Claude dừng. Đây là công cụ độc lập, không phải do Anthropic phát triển. Nếu bạn chỉ cần ghi log hoặc chạy lint, tự viết vài dòng sẽ đơn giản hơn. Chi tiết có trên trang ccn.

10Câu hỏi thường gặp