Bài 6.116 phút · 5 thẻ · 8 bài tập · 1 nhiệm vụ

Vòng đời và các sự kiện hook

Hook là lệnh Claude Code tự chạy mỗi khi sự kiện xảy ra: vòng đời một phiên, cách cấu hình, JSON đầu vào, mã thoát, matcher và an toàn.

Từ cấp 2 tới giờ, mọi thứ bạn dặn Claude đều là lời nhờ: CLAUDE.md ghi "chạy test trước khi xong", skill ghi "không sửa src/". Claude thường làm theo, nhưng không phải lúc nào cũng vậy. Bài 4.3 còn cho thấy một lời giao việc có thể ghi đè hướng dẫn trong file agent. Cấp này giới thiệu thứ không phụ thuộc vào trí nhớ của Claude: hook, một lệnh Claude Code tự chạy mỗi khi một sự kiện xảy ra, lần nào cũng chạy.

Hook là gì

Hook là một lệnh shell bạn tự viết, Claude Code chạy nó ở những điểm cố định trong một phiên: lúc phiên bắt đầu, trước khi Claude dùng một công cụ, sau khi Claude sửa file, lúc Claude trả lời xong…

Khác biệt cốt lõi so với CLAUDE.md và skill:

CLAUDE.md, skill Hook
Ai quyết định chạy Claude, dựa vào hướng dẫn Claude Code, mỗi khi sự kiện xảy ra
Kết quả Có thể khác nhau mỗi lần Lần nào cũng như nhau
Hợp với Việc cần suy nghĩ Việc phải luôn xảy ra

Docs nói gọn: hook cho bạn kiểm soát chắc chắn, việc luôn xảy ra thay vì phụ thuộc vào việc model có chọn làm hay không. Hợp với: định dạng code sau mỗi lần sửa, chặn lệnh nguy hiểm, báo cho bạn khi Claude cần bạn trả lời, đưa thông tin vào đầu mỗi phiên.

Phần lớn hook có kiểu "type": "command", tức một lệnh shell. Ngoài ra còn kiểu http (gửi dữ liệu tới một URL), mcp_tool (gọi công cụ của MCP server), prompt (nhờ một model đánh giá nhanh) và agent (đang thử nghiệm). Cấp này dùng command.

Vòng đời của một phiên

Các sự kiện xảy ra theo ba nhịp:

  • Mỗi phiên: SessionStart khi phiên bắt đầu hoặc được mở lại; SessionEnd khi phiên kết thúc.
  • Mỗi lượt: UserPromptSubmit khi bạn gửi tin nhắn, trước khi Claude xử lý; Stop khi Claude trả lời xong.
  • Mỗi lần dùng công cụ: PreToolUse trước khi chạy, và đây là sự kiện chặn được; PostToolUse sau khi công cụ chạy thành công.

Ngoài ra còn nhiều sự kiện khác, ví dụ Notification khi Claude Code gửi thông báo, SubagentStart và SubagentStop quanh mỗi subagent (cấp 4), PreCompact trước khi nén ngữ cảnh, PermissionRequest khi Claude Code sắp hỏi quyền bạn.

Chúng tôi gắn một hook ghi nhật ký vào sáu sự kiện chính rồi nhờ Claude chạy npm test trong todo-api. File nhật ký ghi lại đúng vòng đời:

SessionStart (startup)
UserPromptSubmit
PreToolUse  (Bash: npm test)
PostToolUse (Bash)
Stop
SessionEnd

Nếu Claude dùng năm công cụ trong một lượt, bạn sẽ thấy năm cặp PreToolUse/PostToolUse nằm giữa UserPromptSubmit và Stop.

Cấu hình một hook

Hook nằm trong khối hooks của một file cài đặt, gồm ba tầng: sự kiện → nhóm matcher (lọc khi nào chạy) → handler (lệnh chạy).

JSON
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{event: .hook_event_name, tool: .tool_name}' >> \"$CLAUDE_PROJECT_DIR\"/.claude/hooks.log"
          }
        ]
      }
    ]
  }
}

Hook này ghi một dòng vào .claude/hooks.log mỗi khi Claude chạy xong một lệnh Bash. jq là công cụ đọc JSON, có sẵn trên macOS bản mới. $CLAUDE_PROJECT_DIR là thư mục gốc dự án, giúp đường dẫn luôn đúng dù Claude đã cd đi đâu.

Đặt ở đâu tùy ai cần:

File Áp dụng Chia sẻ
~/.claude/settings.json Mọi dự án của bạn Không
.claude/settings.json Dự án này Có, commit vào repo
.claude/settings.local.json Dự án này Không

Hook còn đặt được trong plugin, trong cài đặt managed của tổ chức, và trong frontmatter của skill hoặc subagent (bài 3.3, 4.3).

Gõ /hooks để xem mọi hook đang có, nhóm theo sự kiện, kèm nguồn của từng hook. Muốn tạm tắt tất cả, đặt "disableAllHooks": true. Không có cách tắt riêng một hook mà vẫn giữ cấu hình: muốn bỏ thì xóa nó khỏi file.

Hook nhận gì, trả gì

Khi sự kiện xảy ra, Claude Code gửi cho hook một JSON qua stdin. Trường chung gồm session_id, cwd và hook_event_name; mỗi sự kiện có thêm trường riêng. Với PreToolUse khi Claude chạy Bash:

JSON
{
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" }
}

Hook trả lời bằng mã thoát (exit code):

  • Exit 0: không phản đối. Lưu ý: với PreToolUse, exit 0 không có nghĩa là cho phép; lệnh vẫn đi qua luồng hỏi quyền bình thường.
  • Exit 2: chặn. Chữ hook in ra stderr được gửi lại, và với PreToolUse thì Claude đọc được lý do để làm cách khác. Bài 6.3 dùng cách này để chặn rm -rf.
  • Mã khác: với phần lớn sự kiện, việc vẫn chạy tiếp, kèm một thông báo lỗi.

Với SessionStart và UserPromptSubmit, những gì hook in ra stdout (khi exit 0) được thêm vào ngữ cảnh của Claude. Khi thử, chúng tôi cho một hook SessionStart in tên nhánh git. Hỏi Claude "đang ở nhánh nào" mà không cho chạy lệnh gì, Claude trả lời đúng và nói thông tin lấy từ output của hook. Một ví dụ hữu ích hơn, vì Claude không tự biết:

JSON
"SessionStart": [
  { "hooks": [ { "type": "command", "command": "echo \"Node $(node --version)\"" } ] }
]

Cần kiểm soát kỹ hơn thì exit 0 và in một JSON, ví dụ permissionDecision: "deny" kèm lý do. Bài 6.3 sẽ dùng.

Matcher: lọc khi nào chạy

Không có matcher thì hook chạy mọi lần sự kiện xảy ra. Matcher thu hẹp lại, và lọc theo trường tùy sự kiện:

  • Sự kiện công cụ lọc theo tên công cụ: Bash, Edit|Write (sửa hoặc ghi file), mcp__github__.* (mọi công cụ của server GitHub ở cấp 5).
  • SessionStart lọc theo cách phiên bắt đầu: startup, resume, clear, compact.
  • Một số sự kiện như UserPromptSubmit và Stop không có matcher: luôn chạy.

Matcher phân biệt chữ hoa, chữ thường: bash không khớp Bash. Đây là lý do hay gặp nhất khiến hook "không chạy".

Muốn lọc sâu hơn tên công cụ, dùng trường if với cú pháp luật quyền ở bài 1.3 và 5.3, ví dụ "if": "Bash(git *)" để hook chỉ chạy với lệnh git. Docs nhắc rằng if chỉ là bộ lọc kiểu cố gắng; luật cứng thì dùng hệ thống quyền.

Một lưu ý: Claude có thể sửa file bằng lệnh shell, không qua Edit hay Write. Hook chỉ khớp Edit|Write sẽ bỏ sót những lần đó.

Hook chạy với quyền của bạn

Hook là lệnh shell chạy với toàn quyền tài khoản của bạn: đọc, sửa, xóa được mọi thứ bạn làm được. Vì vậy:

  • Trong phiên tương tác, Claude Code giữ lại mọi hook cho tới khi bạn chấp nhận hộp thoại tin thư mục.
  • Nhưng claude -p coi thư mục là đã tin, nên hook commit trong .claude/settings.json của một repo lạ sẽ chạy. Trước khi chạy -p trên repo không phải của bạn, mở .claude/ ra đọc, hoặc tắt hook cho lần chạy đó: claude -p --settings '{"disableAllHooks": true}' "…".

Thói quen khi viết hook:

  • Đặt biến trong ngoặc kép ("$VAR") và dùng đường dẫn đầy đủ với $CLAUDE_PROJECT_DIR.
  • Thử hook trước bằng cách đưa JSON mẫu vào:
    Terminal
    echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh; echo $?
  • Script riêng thì nhớ chmod +x.
  • Trong phiên, nhấn Ctrl+O mở transcript để xem hook đã chặn gì hay báo lỗi gì.

Bài 6.2 dùng PostToolUse để tự định dạng code và chạy test; bài 6.3 dùng PreToolUse để chặn những gì không bao giờ được xảy ra.

Luyện tập bài 6.1

5 thẻ ghi nhớ, 8 bài tập chấm ngay trên trang, 1 nhiệm vụ làm trên máy.

Bắt đầu luyện tập

Tra cứu liên quan

Gõ để tìm trong tra cứu, mẫu cấu hình và bài học. Không dấu cũng được.