Hooks — tự động hóa theo sự kiện tool

English title: Hooks — Automate on Tool Events

Bài 7 trong chuỗi 20 bài về Claude Code. Rules và skills tác động qua nội dung (inject text, procedure). Hooks tác động qua sự kiện: mỗi khi agent gọi một tool (đọc file, sửa file, chạy lệnh), hệ thống có thể chạy logic trước (PreToolUse) hoặc sau (PostToolUse) — validate, cảnh báo, format, log. Bài này làm rõ hook là gì, lifecycle, và ví dụ dùng (block lệnh nguy hiểm, format sau khi sửa file).

Mở đầu: Mỗi lần sửa file, mỗi lần chạy lệnh — hook chạy trước/sau

Agent gọi tool "run terminal command" với nội dung rm -rf ./some-dir. Nếu không có gì can thiệp, lệnh chạy và có thể xóa nhầm. Với PreToolUse hook: hệ thống kiểm tra — nếu tool là "run command" và argument chứa pattern nguy hiểm (vd. rm -rf không có whitelist), hook trả về "block" hoặc "cảnh báo", và agent (hoặc user) phải xác nhận. Ngược lại, sau khi agent sửa file (PostToolUse), hook có thể chạy formatter hoặc linter để file vừa sửa luôn đúng convention. Bạn không cần nhắc "nhớ format" — hook tự làm.

1. Đi sâu: Hook là gì và khi nào dùng

Tại sao quan trọng: Một số việc không thể giải quyết chỉ bằng rule hay skill — ví dụ "chặn lệnh rm -rf" hoặc "sau mỗi lần edit file thì chạy format". Đó là hành động theo sự kiện: khi event X xảy ra (tool A được gọi), chạy logic Y. Hook là cơ chế để gắn logic Y vào event X.

Hiểu sai thường gặp: "Hook = rule chạy mỗi turn." Rule inject text vào context; hook chạy code hoặc script (hoặc inline command) khi có event. Hook nhận input (tool name, args, result) và có thể block, modify (một số nền tảng), hoặc chỉ side-effect (log, format file khác).

Bản chất đúng: Hook = (1) matcher (khi nào chạy — vd. tool == "Edit" và file path là .ts/.tsx), (2) event (PreToolUse vs PostToolUse), (3) action (script, command, hoặc inline logic). PreToolUse chạy trước khi tool thực thi → có thể block hoặc cảnh báo. PostToolUse chạy sau → có thể format, log, ghi state; thường không thay đổi kết quả trả về user mà chỉ side-effect.

2. Khái niệm

• PreToolUse: Event trước khi tool chạy. Input: tool name, arguments. Dùng để: validate (chặn lệnh nguy hiểm, path ngoài phạm vi), inject context, hoặc cảnh báo. Output (tuỳ nền tảng): allow / block / modify request.
• PostToolUse: Event sau khi tool chạy. Input: tool name, args, result. Dùng để: format file vừa sửa, chạy linter, ghi log, gợi ý compact. Không nên dùng để sửa nội dung response hiển thị cho user — chỉ side-effect.
• Matcher: Điều kiện để hook chạy (vd. chỉ khi tool là "Run" và args chứa "rm "). Matcher hẹp giúp tránh hook chạy mọi tool (chậm, nhiễu).
• Lifecycle: User/agent yêu cầu gọi tool → PreToolUse hooks chạy (nếu match) → nếu không bị block, tool thực thi → PostToolUse hooks chạy (nếu match) → kết quả trả về.

3. Code / ví dụ hook (pseudo)

Bạn không paste config thật từ repo; chỉ cần hình dung cấu trúc. Ví dụ PreToolUse — cảnh báo khi chạy lệnh chứa rm -rf:

{
  "matcher": "tool == 'Run' && args.command contains 'rm -rf'",
  "event": "PreToolUse",
  "action": "warn",
  "message": "Detected rm -rf. Confirm scope to avoid data loss."
}

Ví dụ PostToolUse — sau khi Edit file .ts/.tsx thì chạy formatter (pseudo):

{
  "matcher": "tool == 'Edit' && args.path matches '\\.(ts|tsx)$'",
  "event": "PostToolUse",
  "action": "script",
  "script": "format-and-typecheck.sh"
}

Trên thực tế hook có thể là JSON trong file config, với action là tên script hoặc inline command; cú pháp tùy tài liệu chính thức Claude Code.

4. Workflow: Thiết kế hook

1. Xác định event: Cần chạy trước tool (validate, block) → PreToolUse. Cần chạy sau (format, log) → PostToolUse.
2. Viết matcher hẹp: Chỉ match tool và (nếu cần) argument liên quan. Ví dụ: chỉ PreToolUse khi tool là Run và args chứa rm; chỉ PostToolUse khi tool là Edit và path là .ts/.tsx. Tránh match mọi tool → hook chạy liên tục, tốn tài nguyên.
3. Action đơn giản: Hook nên chạy nhanh (vài giây). Script phức tạp (build toàn bộ, test suite) nên để user gọi bằng command thay vì hook.
4. Tránh loop: PostToolUse không nên gọi tool mà bản thân lại kích hoạt PostToolUse (vd. hook Edit → script sửa file → lại Edit). Dùng script chỉ đọc/format, hoặc ghi file khác.

Quy ước: Bắt đầu với 1–2 hook (vd. PreToolUse block rm -rf, PostToolUse format sau Edit). Thêm dần khi cần; tắt hook tạm thời khi debug nếu nền tảng hỗ trợ.

5. Ứng dụng trong AI-centric engineering

• An toàn: PreToolUse block hoặc cảnh báo lệnh nguy hiểm (rm -rf, curl | bash không rõ nguồn). Giảm rủi ro agent (hoặc user) chạy nhầm.
• Chất lượng code: PostToolUse chạy formatter/linter sau mỗi lần agent sửa file → code luôn đúng style, ít chỉnh tay.
• Observability: PostToolUse ghi log (tool name, thời gian, path) để sau này phân tích usage hoặc debug.
• Gợi ý compact: Một số hook PostToolUse (hoặc sau N lần tool) gợi ý user "context đã lớn, cân nhắc /compact" — chi tiết compact ở bài 10.

Bài 8 sẽ nói memory persistence — giữ context qua session (session start/end, load/save state) để mở lại ngày mai vẫn tiếp tục được.

Bài tiếp: Giữ context qua session — memory persistence (bài 8).