Giới thiệu claude-hook-utils: Tiện ích Python tối giản cho việc xây dựng Claude Code Hooks

Claude Code Hooks là các tập lệnh tùy chỉnh chạy tại các thời điểm cụ thể trong quá trình thực thi của Claude Code, cho phép nhà phát triển kiểm soát sâu hơn hành vi của AI. Tuy nhiên, việc xây dựng các hook này từ đầu thường đòi hỏi phải viết đi viết lại nhiều mã mẫu (boilerplate code) như phân tích cú pháp JSON, xác thực cấu trúc đầu vào và định dạng phản hồi.

Giới thiệu claude-hook-utils

claude-hook-utils là một gói tiện ích Python được thiết kế để giải quyết vấn đề trên. Mục tiêu của dự án là loại bỏ sự phức tạp kỹ thuật, giúp lập trình viên tập trung vào logic nghiệp vụ quan trọng nhất.

Theo tác giả Rasmus Godske, thư viện này tuân theo triết lý thiết kế "Một Mô Hình" (One Pattern), nơi người dùng chỉ cần mở rộng lớp HookHandler và ghi đè các hook cần thiết.

Các tính năng nổi bật

• An toàn kiểu dữ liệu (Type Safety): Sử dụng các dataclass có định nghĩa kiểu rõ ràng cho đầu vào và mẫu builder (builder pattern) cho đầu ra, giúp giảm thiểu lỗi trong quá trình phát triển.
• Kiểm soát rõ ràng: Cung cấp các phương thức trợ giúp trên dữ liệu đầu vào, nhưng quyền quyết định bỏ qua, cho phép hoặc từ chối một hành động hoàn toàn thuộc về người dùng.
• Hỗ trợ đa-hook (Multi-Hook Support): Một chương trình Python duy nhất có thể xử lý nhiều loại hook khác nhau như PreToolUse, PostToolUse, v.v.
• Không phụ thuộc nặng nề: Gói cốt lõi có rất ít dependencies; bạn có thể tự tích hợp SDK AI của mình nếu cần.
• Xử lý lỗi thông minh: Áp dụng cơ chế "fail open", nghĩa là nếu hook gặp lỗi, nó sẽ ghi log và cho phép Claude Code tiếp tục chạy thay vì chặn toàn bộ quy trình làm việc.

Các loại Hook được hỗ trợ

Thư viện hỗ trợ bốn loại hook chính:

• PreToolUse: Chạy trước khi một công cụ thực thi. Thường dùng để xác thực đường dẫn tệp, kiểm tra nội dung hoặc chặn các thao tác nguy hiểm.
• PostToolUse: Chạy sau khi công cụ hoàn tất. Dùng để ghi log, kích hoạt hành động theo dõi hoặc thu thập số liệu.
• UserPromptSubmit: Khi người dùng gửi một prompt. Dùng để xác thực prompt, thêm ngữ cảnh hoặc thực thi các chính sách.
• SessionStart: Khi bắt đầu một phiên Claude Code. Dùng để khởi tạo trạng thái hoặc thiết lập biến môi trường.

Cách sử dụng

Để cài đặt, bạn chỉ cần chạy lệnh:

pip install claude-hook-utils

Dưới đây là một ví dụ nhanh về việc xác thực các lớp Data trong PHP phải có chú thích TypeScript:

#!/usr/bin/env python3
"""Validate that Data classes have TypeScript annotation."""
from claude_hook_utils import HookHandler, PreToolUseInput, PreToolUseResponse

class DataClassValidator(HookHandler):
    def pre_tool_use(self, input: PreToolUseInput) -> PreToolUseResponse | None:
        # Bỏ qua nếu không phải tệp Data class
        if not input.file_path_matches('**/app/Data/**/*.php'):
            return None
        
        # Kiểm tra chú thích bắt buộc
        if input.content and '#[TypeScript()]' not in input.content:
            return PreToolUseResponse.deny(
                "Data classes must have #[TypeScript()] annotation for type generation"
            )
        return PreToolUseResponse.allow()

if __name__ == "__main__":
    DataClassValidator().run()

Tính năng ghi log (Logging)

claude-hook-utils cũng tích hợp sẵn một hệ thống logging dựa trên JSONL để dễ dàng gỡ lỗi (debug). Các log được tổ chức theo namespace (tên plugin), giúp nhà phát triển theo dõi chính xác các quyết định (allow/deny) của hook tại từng bước.

Thư viện này là công cụ hữu ích cho các đội ngũ phát triển muốn tích hợp Claude Code sâu hơn vào quy trình CI/CD hoặc quy trình phát triển phần mềm của mình, đảm bảo mã nguồn được tạo ra hoặc chỉnh sửa luôn tuân thủ các tiêu chuẩn và quy tắc của dự án.