Hooks của Claude Code

Hook của Claude Code là code tự chạy quanh mỗi lần agent dùng tool. Nó là bậc chặn sớm nhất: lỗi bị từ chối trước khi lệnh chạy, không phải sau khi CI đỏ. Script ở .claude/hooks/, khai trong .claude/settings.json.

PreToolUse(Bash)

Chặn (exit 2, lý do ra stderr để agent đọc được và tự sửa):

• Các lệnh git nguy hiểm ở luật git.
• wrangler deploy từ máy.
• Vòng lặp poll GitHub Actions: hạn mức GitHub API là của chung mọi phiên, một vòng poll của phiên này làm phiên khác bị từ chối.
• Nuốt đầu ra của script giành số (| tail, > /dev/null): mất dòng in số đã giành là mất dấu.
• Commit khi nhánh tụt quá 100 commit sau origin/main.

Trước khi so regex, bỏ chuỗi trong ngoặc và heredoc: chữ trong một commit message nói "git reset --hard" là chữ, không phải lệnh.

PreToolUse(Write|Edit|Bash)

Chặn ghi một mã yêu cầu mà phiên chưa giành (đọc transcript để biết phiên đã giành gì). Hai phiên dùng cùng một số là hai việc không phân biệt được trong sổ.

SessionStart

• git fetch, fast-forward cây chung khi an toàn.
• Cảnh báo: nhánh tụt sau main, node_modules cũ, ổ dưới 10 GB, việc phiên khác đang giữ, production lệch main (đọc kết quả gate production một lần, không poll).
• Gọi script của repo thì kiểm existsSync trước: script chưa có trên cây cũ thì node thoát 1 và bị đọc nhầm là lỗi.

PostToolUse

• Sau một push lên main thành công: nhắc chạy retro cuối phiên.
• Khi ghi file skill: chạy ngay các gate của skill.

Luật cho chính hook

• Hook không bao giờ làm hỏng tool vì lỗi của chính nó: try/catch rồi exit 0.
• Nhưng lỗi bị nuốt phải được thử bằng tay để thấy đầu ra (bẫy 3): một hook hỏng im lặng trông y hệt một hook không tìm thấy gì.
• Mỗi hook có test, và test nằm trong gate.

Ở Conan hôm nay

Sự kiện	Hook	Làm gì	Tự kiểm
SessionStart	scripts/cloud-bootstrap.sh	npm ci 15 thư mục nếu lockfile mới hơn node_modules (42 s khi lạnh)	Không
SessionStart	scripts/hooks/session-warnings.mjs (từ 18.10.2026)	Cảnh báo clone cũ, tụt > 100 commit, ổ < 10 GB	8 mẫu
PreToolUse	scripts/hooks/deps-docs-guard.mjs	Chặn đổi phiên bản gói khi chưa tra Context7 đúng gói	80 mẫu
PreToolUse(Bash)	scripts/hooks/danger-guard.mjs (từ 18.10.2026)	Chặn deploy từ máy, ghi D1 --remote, push --force, --no-verify; trên cây chung chặn add -A, reset --hard, stash, restore, clean -f; commit khi tụt > 100	48 mẫu
PreToolUse(Bash)	.claude/hooks/pre-push-guards.sh	Trước git push, chạy run-guards --fast	Không
PostToolUse	scripts/hooks/post-edit-guards.mjs	Bắt gạch dài trong file vừa sửa	Không
Stop	scripts/hooks/stop-guards.mjs	qc-scan + workspace-deps khi cây bẩn	Không

Gác hooks kiểm mọi hook trỏ tới file có thật, đúng cú pháp, không khoá trùng, và chạy --self-test của hook nào có. Vòng poll CI cố ý không bị chặn (xem Audit, mục 4). Xem Audit, mục 4.