Hook của Claude Code: kiểm soát hành động của tác nhân theo quy tắc xác định

Cấu trúc của một hook

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\"" }
        ]
      }
    ]
  }
}

Gồm ba phần: sự kiện, bộ so khớp (biểu thức chính quy áp dụng cho tên công cụ đối với sự kiện công cụ; bỏ qua để khớp với mọi thứ) và một hoặc nhiều lệnh. Lệnh nhận một đối tượng JSON trên stdin mô tả sự kiện — đối với sự kiện công cụ, đối tượng này bao gồm tool_name và tool_input, nhờ đó ví dụ ở trên tìm được tệp vừa được chỉnh sửa. Đặt cấu hình này trong .claude/settings.json để chia sẻ cùng kho mã, ~/.claude/settings.json để dùng riêng, hoặc chạy /hooks và để Claude Code ghi cấu hình.

Các sự kiện

• PreToolUse — trước khi một công cụ chạy. Sự kiện duy nhất có thể chặn: mã thoát 2 hủy lệnh gọi và Claude đọc stderr của bạn để biết lý do.
• PostToolUse — sau khi một công cụ thực thi thành công. Chạy trình định dạng, trình kiểm tra lint và kiểm tra kiểu trên tệp đã chỉnh sửa.
• UserPromptSubmit — khi bạn gửi prompt; có thể bổ sung ngữ cảnh hoặc từ chối prompt.
• Stop / SubagentStop — khi tác nhân (hoặc tác nhân phụ) sắp hoàn tất. Mã thoát 2 ở đây có nghĩa là "chưa xong" — cách dùng điển hình là không cho dừng khi kiểm thử vẫn thất bại.
• PreCompact — trước /compact; lưu mọi nội dung bạn cần từ bản ghi hội thoại đầy đủ.
• SessionStart — khi một phiên bắt đầu hoặc tiếp tục; nạp môi trường, in lời nhắc.
• Notification — khi Claude Code cần bạn chú ý (yêu cầu cấp quyền, trạng thái chờ); kết nối sự kiện này với thông báo trên màn hình hoặc Slack.

Chặn lệnh nguy hiểm

#!/usr/bin/env bash
# .claude/hooks/guard.sh  -- PreToolUse, matcher: Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|--no-verify'; then
  echo "blocked by guard.sh: $cmd" >&2
  exit 2
fi
exit 0

Mã thoát 2 là quy ước: lệnh gọi công cụ không được thực hiện, và mọi nội dung hook in ra stderr trở thành lời giải thích mà Claude nhìn thấy, để nó có thể chọn cách tiếp cận khác thay vì thử lại cùng một cách. Mọi mã thoát khác không đều được ghi log nhưng không chặn.

"Không dừng cho đến khi các kiểm thử thành công"

#!/usr/bin/env bash
# Stop hook: refuse to finish while the suite is red
if ! npm test --silent >/tmp/claude-test.log 2>&1; then
  echo "Tests are failing; fix them before finishing:" >&2
  tail -n 40 /tmp/claude-test.log >&2
  exit 2
fi

Kết hợp với giới hạn --max-turns trong các lần chạy không có giao diện để một lỗi thực sự không thể khắc phục không gây lặp vô tận.

Hook so với CLAUDE.md và quyền

CLAUDE.md là lời hướng dẫn mà mô hình đọc; /permissions là danh sách những việc nó được phép làm mà không cần hỏi; hook là mã chạy trong mọi trường hợp. Dùng CLAUDE.md cho phong cách và ngữ cảnh, quyền để xác định khi nào được phép thực hiện và khi nào cần hỏi, còn hook cho mọi điều phải luôn được bảo đảm — định dạng, quét thông tin bí mật, điều kiện kiểm thử, nhật ký kiểm toán. Chúng kết hợp với nhau: một quyền cho phép Bash(git *) chạy, nhưng hook PreToolUse vẫn chặn git push --force.

Hook và cổng API

Hook chạy cục bộ và không bao giờ gọi API, nên không có gì thay đổi khi Claude Code trỏ đến ANTHROPIC_BASE_URL=https://aiprimetech.io. Một cách kết hợp hữu ích: hook Stop in ra /costthông tin sử dụng theo kiểu này từ nhật ký của bạn, để một nhóm dùng tín dụng trả theo mức sử dụng thấy được chi phí của từng phiên khi phiên kết thúc.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

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

AI Prime Tech là một cổng API độc lập, không có quan hệ liên kết với Anthropic và không được Anthropic chứng thực hay tài trợ. “Claude” và “Claude Code” là các nhãn hiệu của Anthropic. Các tính năng Claude Code được mô tả ở đây dựa trên tài liệu công khai của Anthropic tại thời điểm viết và thường xuyên thay đổi; giá và danh sách mô hình trên trang này được đọc từ cấu hình hiện hành của cổng API này.