# Hooks trong Claude Code: tự động chặn và kiểm tra trước khi AI làm

URL: https://opcaios.org/blog/hooks-trong-claude-code
Ngày: 2026-11-18
Cập nhật: 2026-11-04
Tác giả: Lê Quốc Nghĩa
Chuyên mục: Hướng dẫn

Hooks trong [Claude Code](/tien-ich/claude-code) là các lệnh do bạn tự định nghĩa, được Claude Code tự chạy ở những thời điểm cố định trong một phiên làm việc: trước khi gọi công cụ, sau khi sửa file, khi cần bạn chú ý, khi trả lời xong. Theo trang "Automate actions with hooks" trong tài liệu Claude Code tại code.claude.com (đọc ngày 03/11/2026), hook cho bạn quyền kiểm soát có tính xác định: việc chắc chắn xảy ra, không phụ thuộc mô hình AI có "nhớ" làm hay không. Bài này không hứa hook biến Claude Code thành an toàn tuyệt đối: một hook viết sai có thể bỏ lọt lệnh nguy hiểm, và bản thân hook chạy lệnh với toàn quyền tài khoản của bạn. Bài đi qua các sự kiện chính, cách một hook chặn lệnh bằng mã thoát hoặc JSON, ba ví dụ lấy từ tài liệu (chặn lệnh nguy hiểm, định dạng sau khi sửa, thông báo), rủi ro bảo mật, khác biệt với quyền (permissions) và CLAUDE.md, và nói thẳng OPCAIOS mới dùng hook đến đâu.

![Sơ đồ hooks trong Claude Code: Claude định gọi công cụ, sự kiện PreToolUse chạy hook, hook đọc JSON từ stdin, thoát mã 0 để đi tiếp vào luồng quyền hoặc mã 2 để chặn và gửi lý do cho Claude; sau khi công cụ chạy xong, PostToolUse chạy định dạng; Notification và Stop gửi thông báo cho người dùng](https://opcaios.org/images/blog/hooks-trong-claude-code/so-do.webp)
*Hook chen vào vòng làm việc của Claude Code: trước công cụ, sau công cụ, khi cần người. Sơ đồ: OPCAIOS.*

## Hook trong Claude Code là gì và khác gì lời dặn trong CLAUDE.md?

Hook trong Claude Code là một quy tắc được phần mềm thực thi, còn lời dặn trong CLAUDE.md là ngữ cảnh mà mô hình có thể làm theo hoặc bỏ sót. Trang memory của tài liệu Claude Code (đọc ngày 03/11/2026) nói rõ: muốn chặn một hành động bất kể Claude quyết định gì, hãy dùng hook PreToolUse thay vì viết vào CLAUDE.md. Hook được khai báo trong khối `hooks` của file cài đặt, gồm ba lớp: tên sự kiện (khi nào chạy), `matcher` (lọc theo tên công cụ, ví dụ chỉ `Edit|Write`), và danh sách lệnh cần chạy. Kiểu phổ biến nhất là `"type": "command"`, chạy một lệnh shell. Tài liệu còn liệt kê các kiểu khác: gửi dữ liệu tới một URL (`http`), gọi công cụ của một máy chủ MCP (`mcp_tool`), nhờ mô hình đánh giá một lượt (`prompt`), và kiểu `agent` đang ở dạng thử nghiệm. Người làm một mình nên bắt đầu với kiểu `command` vì dễ đọc, dễ thử và dễ gỡ. Nếu chưa có file hướng dẫn, đọc trước bài [CLAUDE.md là gì](/blog/claude-md-la-gi).

## Những sự kiện hook chính nào cần biết?

Claude Code có hơn ba mươi sự kiện hook, nhưng người mới chỉ cần nắm khoảng tám sự kiện. Bảng dưới tóm tắt từ mục "How hooks work" trong tài liệu (đọc ngày 03/11/2026):

| Sự kiện | Khi nào chạy | Dùng để |
|---|---|---|
| `SessionStart` | Phiên bắt đầu hoặc tiếp tục | Nạp thêm ngữ cảnh, kiểm tra môi trường |
| `UserPromptSubmit` | Bạn gửi lời nhắc, trước khi Claude xử lý | Thêm ngữ cảnh, chặn lời nhắc |
| `PreToolUse` | Trước khi một công cụ chạy, có thể chặn | Chặn lệnh nguy hiểm, bảo vệ file |
| `PermissionRequest` | Khi một lệnh cần quyết định về quyền | Tự duyệt hoặc từ chối có điều kiện |
| `PostToolUse` | Sau khi công cụ chạy thành công | Định dạng, lint, ghi nhật ký |
| `Notification` | Claude Code gửi thông báo (chờ bạn nhập hoặc duyệt) | Báo ra màn hình, điện thoại |
| `Stop` | Claude trả lời xong một lượt | Báo xong, kiểm tra cuối |
| `SessionEnd` | Phiên kết thúc | Dọn dẹp |

Tài liệu lưu ý `Stop` chạy mỗi khi Claude trả lời xong, không chỉ khi hoàn thành cả nhiệm vụ, và `PostToolUse` không thể hoàn tác vì công cụ đã chạy rồi. Gõ `/hooks` trong phiên để xem mọi hook đang được cấu hình.

## Hook chặn một lệnh bằng cách nào?

Hook chặn một lệnh bằng mã thoát 2 hoặc bằng một đối tượng JSON in ra stdout. Theo tài liệu (đọc ngày 03/11/2026), khi sự kiện xảy ra, Claude Code gửi dữ liệu dạng JSON vào stdin của script, gồm `tool_name` và `tool_input`; với công cụ Bash, trường `tool_input.command` chứa lệnh shell sắp chạy. Script quyết định theo ba cách:

1. Thoát mã 0: không phản đối. Với PreToolUse, lệnh vẫn đi tiếp vào luồng xin quyền bình thường, mã 0 không có nghĩa là đã duyệt.
2. Thoát mã 2: chặn. Nội dung ghi ra stderr được chuyển cho Claude làm phản hồi để Claude đổi cách làm. Một số sự kiện như SessionStart không chặn được.
3. Mã khác: thường là lỗi không chặn, hành động vẫn diễn ra. Đây là bẫy hay gặp: script lỗi cú pháp thoát mã 1 thì lệnh nguy hiểm vẫn chạy.

Muốn kiểm soát chi tiết hơn, thoát mã 0 và in JSON với `permissionDecision` là `deny`, `ask` hoặc `allow`. Tài liệu khuyên chọn một trong hai cách cho mỗi hook, không trộn. Khi nhiều hook cùng khớp, kết quả chặt nhất thắng, theo thứ tự deny, defer, ask, allow.

## Ví dụ 1: chặn lệnh xoá nguy hiểm trước khi chạy

Ví dụ này phỏng theo script mẫu "Hook output" trong tài liệu (mẫu gốc chặn lệnh `drop table`), đổi điều kiện thành `rm -rf`. Lưu file thành `.claude/hooks/block-rm-rf.sh`, chạy `chmod +x` cho file:

```bash
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "rm -rf"; then
  echo "Blocked: rm -rf is not allowed" >&2
  exit 2
fi

exit 0
```

Đăng ký trong `.claude/settings.json` của dự án:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}
```

Giới hạn cần biết: so khớp chuỗi rất dễ lọt, ví dụ `rm -r -f` hay `rm -fr` không chứa đúng chuỗi `rm -rf`. Hook kiểu này là lưới an toàn thêm, không thay quy tắc quyền. Script cần công cụ `jq` để đọc JSON. Tài liệu có thêm ví dụ chặn sửa file `.env`, `package-lock.json` và thư mục `.git/` theo cùng cách.

## Ví dụ 2: tự định dạng mã sau mỗi lần sửa file

Định dạng sau khi sửa là ví dụ PostToolUse đơn giản nhất: mỗi khi Claude dùng công cụ Edit hoặc Write, hook lấy đường dẫn file và chạy Prettier. Cấu hình lấy nguyên từ tài liệu (đọc ngày 03/11/2026), đặt trong `.claude/settings.json`:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}
```

Muốn chạy lint thay vì định dạng, đổi lệnh phía sau. Khi chạy thành công, hook không in gì vào hội thoại; kiểm tra bằng cách mở file vừa sửa. Lưu ý hook này chỉ bắt thay đổi qua Edit và Write; tài liệu gợi ý sự kiện `FileChanged` nếu file còn bị lệnh Bash sửa.

## Ví dụ 3: thông báo khi Claude cần bạn hoặc đã xong

Thông báo là hook vô hại nhất để tập. Trên macOS, tài liệu (đọc ngày 03/11/2026) đưa cấu hình sau cho `~/.claude/settings.json`:

```json
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}
```

Linux dùng `notify-send`, Windows có lệnh PowerShell riêng trong tài liệu. Muốn báo khi Claude trả lời xong, gắn lệnh tương tự vào sự kiện `Stop`. Nếu file cài đặt đã có khoá `hooks`, thêm sự kiện mới cạnh các sự kiện cũ, đừng thay cả khối.

## Hook có rủi ro bảo mật gì?

Rủi ro lớn nhất của hook là hook chạy lệnh shell với toàn bộ quyền của tài khoản người dùng. Mục "Security considerations" trong tài liệu hooks (đọc ngày 03/11/2026) cảnh báo hook có thể sửa, xoá hoặc đọc bất kỳ file nào tài khoản của bạn truy cập được, nên phải đọc và thử mọi lệnh trước khi thêm. Ba điểm thực dụng:

1. Hook đặt trong `.claude/settings.json` của repo đi theo git, nên clone repo của người khác là nhận luôn hook của họ. Trong phiên tương tác, Claude Code giữ hook lại cho tới khi bạn chấp nhận hộp thoại tin cậy thư mục. Nhưng với chế độ không tương tác `claude -p` hoặc SDK, thư mục được coi là tin cậy và hook trong repo chạy luôn. Trước khi chạy `-p` trên repo lạ, đọc thư mục `.claude/` hoặc tắt hook bằng `--settings '{"disableAllHooks": true}'`.
2. Dữ liệu vào hook do mô hình sinh ra, có thể chứa ký tự lạ. Tài liệu khuyên kiểm tra đầu vào, luôn đặt biến shell trong ngoặc kép, chặn `..` trong đường dẫn, dùng đường dẫn tuyệt đối, tránh đụng `.env` và khoá.
3. Hook kiểu `http` gửi dữ liệu sự kiện ra ngoài; chỉ trỏ tới địa chỉ bạn kiểm soát.

Xem thêm bài [bảo mật khi dùng AI viết code](/blog/bao-mat-khi-dung-ai-viet-code).

## Hook khác quyền (permissions) và CLAUDE.md thế nào?

Ba cơ chế này bổ sung cho nhau, khác nhau ở mức cưỡng chế và độ linh hoạt:

| | CLAUDE.md | Quy tắc quyền (permissions) | Hook |
|---|---|---|---|
| Bản chất | Hướng dẫn trong ngữ cảnh | Danh sách allow, ask, deny do Claude Code thực thi | Script do bạn viết, Claude Code chạy |
| Có chắc chắn không | Không, mô hình có thể bỏ sót | Có | Có, nếu script đúng |
| Linh hoạt | Cao, viết bằng lời | Thấp, theo mẫu như `Bash(git push *)` | Cao, kiểm tra được mọi điều kiện |
| Hợp với | Quy ước, thói quen | Cấm hẳn một loại lệnh | Kiểm tra theo ngữ cảnh, tự động hoá |

Theo trang permissions (đọc ngày 03/11/2026), quy tắc được xét theo thứ tự deny, ask, allow, và hook thoát mã 2 chặn lệnh trước khi quy tắc quyền được xét. Trang hooks thêm rằng hook trả `deny` vẫn có hiệu lực cả ở chế độ bỏ qua quyền, còn hook trả `allow` không vượt được quy tắc deny trong cài đặt. Tài liệu cũng nói bộ lọc `if` của hook chỉ là cố gắng tốt nhất, nên với việc cấm tuyệt đối thì dùng quy tắc quyền. Cách kết hợp hợp lý: deny cứng trong permissions, hook cho kiểm tra mềm và tự động hoá, CLAUDE.md cho quy ước. Chế độ quyền được bàn kỹ ở bài [plan mode và chế độ quyền](/blog/plan-mode-va-che-do-quyen-trong-claude-code).

## Kinh nghiệm của OPCAIOS

Nói thẳng: OPCAIOS có cấu hình hook trong Claude Code, nhưng hiện CHỈ dùng để báo trạng thái phiên cho một công cụ quản lý terminal (phiên bắt đầu, kết thúc, đang chờ quyền). Kiểm tra ngày 03/11/2026, chúng tôi CHƯA có hook nào chặn lệnh nguy hiểm, chưa có hook tự chạy lint hay định dạng sau khi sửa file.

Vậy hiện an toàn dựa vào đâu:

1. Phiên thường chạy chế độ tự động có bộ phân loại an toàn của Claude Code; từng có lần lệnh bị chặn và phải viết lại lệnh.
2. Hành động khó đảo ngược (xoá, gửi tin nhắn, xuất bản) vẫn cần chủ đồng ý.
3. Quy tắc như "chỉ commit đúng file của mình" và "chạy thử đồng bộ trước khi deploy" nằm trong file hướng dẫn và bộ nhớ, tức là hướng dẫn, không phải cưỡng chế.

Bài học rút ra: những quy tắc đang chỉ nằm trong ghi chú là ứng viên đầu tiên để chuyển thành hook hoặc quy tắc deny. Chúng tôi chưa làm, nên chưa có kinh nghiệm thật về hook chặn để chia sẻ.

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

### Hook trong Claude Code đặt ở đâu?

Hooks trong Claude Code được khai báo trong khối `hooks` của file cài đặt JSON. Theo tài liệu (đọc ngày 03/11/2026), `~/.claude/settings.json` áp dụng cho mọi dự án trên máy, `.claude/settings.json` cho một dự án và có thể commit vào git, `.claude/settings.local.json` cho một dự án nhưng chỉ trên máy bạn. Hook còn có thể đến từ cài đặt quản lý của tổ chức, từ plugin, hoặc khai báo trong frontmatter của skill và subagent. Gõ `/hooks` để xem toàn bộ hook đang chạy, nhóm theo sự kiện.

### Hook có chặn được mọi lệnh nguy hiểm không?

Hook không chặn được mọi lệnh nguy hiểm, vì hook chỉ chặn đúng những gì script của bạn nhận ra. Script so khớp chuỗi đơn giản dễ bị lọt bởi cách viết lệnh khác, và script lỗi thoát mã 1 thì hành động vẫn diễn ra. Vì vậy hãy dùng quy tắc deny trong permissions cho các lệnh cấm tuyệt đối, dùng hook như lớp kiểm tra thêm, và vẫn duyệt thay đổi trước khi đưa lên môi trường thật.

### Không biết lập trình có viết được hook không?

Người không biết lập trình vẫn có thể bắt đầu với hooks trong Claude Code. Tài liệu nói bạn có thể mô tả hook mình muốn và nhờ Claude viết giúp. Cách an toàn cho người mới: bắt đầu bằng hook thông báo vì vô hại, đọc kỹ từng dòng lệnh Claude đề xuất, thử trên dự án thử trước, và chỉ thêm hook chặn sau khi đã hiểu mã thoát 0 và 2. Đừng chép hook từ nguồn lạ mà không đọc, vì hook chạy với toàn quyền tài khoản của bạn.

### Hook có làm chậm Claude Code không?

Có thể, vì mỗi hook là một tiến trình chạy thêm. Theo tài liệu, hook kiểu command có thời gian chờ mặc định 10 phút, riêng một số sự kiện như UserPromptSubmit thấp hơn, và có thể đặt lại bằng trường `timeout`. Hook định dạng chạy sau mỗi lần sửa file sẽ cộng thêm thời gian cho từng lần sửa. Dùng `matcher` và trường `if` để hook chỉ chạy khi cần, ví dụ chỉ với lệnh `git`.

### Tắt toàn bộ hook thế nào khi có sự cố?

Đặt `"disableAllHooks": true` trong file cài đặt. Tài liệu lưu ý giá trị cuối cùng tuỳ thứ tự ưu tiên giữa các file cài đặt, và hook từ cài đặt quản lý của tổ chức vẫn chạy trừ khi được tắt ở chính đó. Với một lần chạy `claude -p` trên repo lạ, có thể truyền `--settings '{"disableAllHooks": true}'`. Nếu muốn có người hướng dẫn dựng hook, quyền và CLAUDE.md theo dự án thật của bạn, xem [khoá đào tạo ứng dụng AI](/services/dao-tao-ung-dung-ai) của OPCAIOS.

*Nguồn: tài liệu Claude Code của Anthropic, các trang "Automate actions with hooks" (code.claude.com/docs/en/hooks-guide), "Hooks reference" (code.claude.com/docs/en/hooks), permissions và memory, đọc ngày 03/11/2026; tên sự kiện, thời gian chờ và hành vi theo phiên bản có thể thay đổi; ví dụ chặn rm -rf là bản phỏng theo mẫu của tài liệu, OPCAIOS mới chạy thử script với dữ liệu JSON mẫu (thoát 2 khi có rm -rf, 0 khi không), chưa dùng như hook thật trong phiên. Kinh nghiệm là của OPCAIOS.*
