SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor

Claude Code Hooks: Cách hoạt động và cấu hình

Tìm hiểu Claude Code hooks nằm ở đâu, event nào kích hoạt, vì sao exit code 2 hủy tool call và rủi ro bảo mật khi chạy shell command.

Claude Code hook là gì

Claude Code hook là các shell command mà Claude Code tự chạy tại những thời điểm cố định trong vòng đời của chính nó. Đây là điểm khác biệt hoàn toàn giữa hook và rules file. Chỉ thị trong CLAUDE.md là lời khuyên, và model sẽ cân nhắc chỉ thị đó cùng mọi nội dung khác trong context. Hook là code, và nó sẽ chạy dù model có đồng ý hay không. Nếu agent liên tục bỏ qua formatter mà bạn đã nhắc hai lần, bạn không cần chỉ thị cứng rắn hơn. Bạn cần một hook.

Cơ chế này khá nhỏ. Bạn đăng ký một command trong settings file dưới tên một event. Khi event đó xảy ra, Claude Code chạy command của bạn và ghi dữ liệu event vào standard input (stdin) dưới dạng JSON (JavaScript object notation). Command của bạn đọc dữ liệu đó, thực hiện công việc rồi trả về exit status. Exit 2 từ hook PreToolUse sẽ hủy tool call trước khi nó chạy. Mọi nội dung script ghi vào standard error (stderr) sẽ được trả lại cho model làm lý do, trừ khi hook cũng in ra JSON có chứa quyết định chặn; khi đó lý do trong JSON được ưu tiên.

Tên event và tên field trong phần này lấy từ tài liệu tham chiếu về hooks của Claude Code, được kiểm tra vào ngày November 12, 2026. Giao diện này thay đổi nhanh, vì vậy hãy kiểm tra tài liệu tham chiếu cho phiên bản bạn đang dùng trước khi sao chép JSON từ bất kỳ blog post nào, kể cả bài này. In tài liệu của phiên bản đang dùng bằng claude --version.

Vị trí lưu cấu hình hook

Hook là một khối JSON trong file settings. Có 6 vị trí có thể chứa hook, và phạm vi của file cũng là phạm vi của hook.

  • ~/.claude/settings.json: áp dụng cho mọi project trên máy của bạn, không áp dụng cho máy của người khác.
  • .claude/settings.json: áp dụng cho một project, được commit vào repository, nên mọi người clone project đó đều nhận được hook.
  • .claude/settings.local.json: áp dụng cho một project, chỉ trên máy của bạn.
  • Managed policy settings: áp dụng trên toàn tổ chức và do administrator thiết lập.
  • hooks/hooks.json bên trong plugin, có hiệu lực khi plugin đó được enable.
  • Frontmatter của skill hoặc subagent. Hook của skill tiếp tục có hiệu lực trong phần còn lại của session sau khi skill được gọi. Hook của subagent có hiệu lực trong thời gian subagent đó chạy.

Các entry của hook trong những file này được merge thay vì ghi đè lẫn nhau. File settings của project thêm hook vào các hook trong user settings, thay vì thay thế chúng. Vì vậy, một event có thể chứa nhiều hook từ nhiều file. Thiết lập "disableAllHooks": true sẽ tắt các hook, trừ một trường hợp: hook từ managed policy settings vẫn tiếp tục chạy, trừ khi setting đó cũng được áp dụng trong managed settings.

Chạy /hooks trong một session để liệt kê mọi hook đang được đăng ký, nhóm theo event, kèm source file và matcher của từng hook. Menu này chỉ đọc, nên bạn phải chỉnh sửa hook trong file settings. File watcher thường tự phát hiện thay đổi mà không cần restart.

Các event hook nào tồn tại trong Claude Code

Tài liệu tham chiếu hooks liệt kê 33 event, từ SessionStart đến SessionEnd, bao quát compaction, subagent, worktree và file cấu hình. Khi làm việc trên server, bạn thường chỉ dùng một số event.

  • PreToolUse: chạy trước khi tool call thực thi, ngoại trừ EndConversation. Đây là event có thể chặn thao tác.
  • PostToolUse: chạy sau khi tool call thành công, ngoại trừ EndConversation. PostToolUseFailure chạy thay thế khi tool call thất bại. Vì vậy, hook cần nhận biết mọi kết quả phải dùng cả hai event.
  • PermissionRequest: chạy khi tool call cần quyết định cấp quyền, tức thời điểm prompt phê duyệt xuất hiện.
  • UserPromptSubmit: chạy khi bạn gửi prompt, trước khi Claude xử lý prompt. stdout dạng plain text từ hook chạy thành công sẽ được thêm vào context của model.
  • SessionStart và SessionEnd: chạy ở mỗi đầu và cuối session. SessionStart cũng chạy sau compaction, với giá trị matcher là compact.
  • Stop: chạy khi Claude hoàn tất phản hồi. Event này chạy một lần cho mỗi lượt, không phải một lần cho mỗi task hoàn tất.

Với các event hỗ trợ matcher, một group có thể chứa matcher để quyết định occurrence nào sẽ chạy hook. Đối với các event của tool, matcher lọc theo tên tool. Vì vậy, "Edit|Write" chỉ chạy khi chỉnh sửa file, không chạy cho thao tác nào khác. Matcher phân biệt chữ hoa và chữ thường. Matcher rỗng sẽ chạy ở mọi occurrence. Tool từ một server MCP (model context protocol) có tên dạng mcp__<server>__<tool>. Do đó, matcher "mcp__github__.*" sẽ bắt các tool của một server, nhưng không bắt tool của các server khác.

Stop hook có một điểm cần lưu ý trước khi bạn viết hook. Một hook Stop khi chặn thao tác sẽ yêu cầu model tiếp tục xử lý. Theo mặc định, Claude Code sẽ bỏ qua block tiếp theo sau 8 lần tiếp tục liên tiếp; bộ đếm được reset mỗi khi Claude gọi tool. Hãy đọc trường stop_hook_active từ input của hook và exit 0 khi giá trị này là true. Nếu không, hook có thể liên tục yêu cầu Claude tiếp tục xử lý.

Dữ liệu hook nhận trên stdin

Khi Claude sắp chạy npm test, một hook PreToolUse trên Bash đọc dữ liệu sau từ stdin:

{
  "session_id": "abc123",
  "cwd": "/home/deploy/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Các trường đầu vào phổ biến gồm session_id, cwd, transcript_path và hook_event_name; permission_mode không được gửi trong mọi event. Các event của tool bổ sung tool_name, tool_input và tool_use_id. Những event khác có các trường riêng: UserPromptSubmit nhận nội dung prompt, còn SessionStart nhận một source gồm startup, resume, clear, compact hoặc fork.

jq là cách thông thường để đọc dữ liệu này trong shell script, nhưng image server tối giản không có lệnh này. Trước tiên, hãy cài đặt nó bằng sudo apt install -y jq trên Ubuntu và Debian.

Exit status ảnh hưởng thế nào đến tool call đang thực hiện

Có ba kết quả.

  • Exit 0 nghĩa là thành công, và mọi trường JSON hợp lệ trong quyết định vẫn có hiệu lực, bao gồm cả block hoặc từ chối. Trên PreToolUse, exit 0 không kèm quyết định không có nghĩa là được phê duyệt; luồng cấp quyền thông thường vẫn chạy. Trên UserPromptSubmit, UserPromptExpansion, SessionStart và PostModelSwitch, stdout dạng văn bản thuần được thêm vào context của model. Với hầu hết event khác, stdout chỉ được ghi vào debug log.
  • Exit 2 block action trên những event có thể bị block, trong đó có PreToolUse, và stderr trở thành thông báo đi kèm block, trừ khi output JSON chứa quyết định block; khi đó reason trong JSON được ưu tiên. Ai đọc thông báo này phụ thuộc vào event. Trên PreToolUse và Stop, model thấy thông báo đó dưới dạng reason. Trên UserPromptSubmit và PreModelSwitch, thông báo được hiển thị cho bạn và không được thêm vào context của model. Trên PostToolUse và PostToolUseFailure, vốn không thể bị block, block sẽ bị bỏ qua, nhưng stderr vẫn được gửi đến model dưới dạng feedback. Với hầu hết event khác không thể bị block, stderr chỉ được hiển thị cho bạn hoặc bị bỏ qua. Trên Stop, SubagentStop, TaskCompleted và hook UserPromptSubmit của plugin, exit 2 với stdout rỗng và lỗi thiếu file trong stderr được xử lý như một lỗi không block.
  • Mọi exit code khác với stdout dạng văn bản thuần hoặc rỗng thường là lỗi không block. Transcript hiển thị thông báo lỗi hook, kèm dòng đầu tiên của stderr sau phần text Failed with non-blocking status code:. JSON hợp lệ vẫn có thể quyết định kết quả trên các event như PreToolUse, trừ khi lỗi của hook block action. WorktreeCreate fail khi exit khác 0, còn WorktreeRemove fail khi exit khác 0 nếu thư mục vẫn tồn tại sau đó.

Nếu cần làm gì khác ngoài block hoặc không thực hiện gì, hãy dùng exit 0 và in một object JSON ra stdout. Hook PreToolUse đưa ra quyết định bằng permissionDecision:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

"allow" bỏ qua interactive prompt khi permission rules và yêu cầu phê duyệt của tool cho phép, "deny" hủy call và gửi reason cho model, còn "ask" yêu cầu xác nhận. Chọn một kiểu cho mỗi hook. Nếu kết hợp exit 2 với quyết định JSON trên stdout, block vẫn được giữ nguyên, ngay cả khi JSON ghi "allow".

Khi nhiều hook khớp với cùng một event, chúng chạy song song; prompt hook và agent hook được giới hạn ở 12 hook chạy đồng thời. deny từ một hook không dừng các hook cùng cấp, nên logging hook vẫn ghi dòng log trong khi guardrail hook từ chối cùng call đó. Với PreToolUse, Claude Code sau đó gộp các câu trả lời và giữ kết quả hạn chế nhất, theo thứ tự deny, defer, ask, allow.

Ví dụ 1: chặn một lệnh phá hoại trước khi lệnh chạy

Lưu nội dung này thành .claude/hooks/block-destructive.sh trong project của bạn:

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

Cấp quyền thực thi cho file, rồi đăng ký file đó trên PreToolUse trong .claude/settings.json:

chmod +x .claude/hooks/block-destructive.sh
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking the command against policy"
          }
        ]
      }
    ]
  }
}

Chạy thử script thủ công trước khi tin dùng, vì hook tự crash khi xử lý input của chính nó thường sẽ fail open nếu onFailure chưa được set. Trên Windows không có Git Bash, một command hook dạng shell của PreToolUse hoặc PermissionRequest nếu fail có thể chặn lần gọi tool:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

Bạn sẽ thấy dòng Blocked by policy: trên stderr và exit code là 2. Truyền vào một lệnh vô hại như ls -la; bạn sẽ không thấy output nào và exit code là 0. Trong session, lần gọi bị từ chối sẽ xuất hiện trong transcript cùng với message của bạn làm lý do, và model sẽ đọc message đó rồi điều chỉnh.

Một thuộc tính khiến cách này đáng dùng: hook PreToolUse chạy trước bước kiểm tra permission mode, trong mọi permission mode, nên deny vẫn có hiệu lực ngay cả dưới bypassPermissions. Vì vậy hook hữu ích khi dùng cùng chế độ auto và các cài đặt permission của Claude Code, trong đó các prompt được giảm bớt nhưng hook vẫn chạy.

Hãy hiểu đúng giới hạn của cách này. So khớp pattern trên chuỗi lệnh chỉ là guardrail chống việc agent bất cẩn. Nó không phải boundary chống agent cố tình lách, vì cùng một lệnh có thể được viết theo dạng mà grep của bạn không nhìn thấy. Các rule bắt buộc phải nằm trong permission system và trong account mà process chạy dưới quyền đó.

Ví dụ 2: format và lint sau mỗi lần chỉnh sửa

PostToolUse với matcher Edit|Write chạy sau khi một trong hai tool chỉnh sửa file thực thi thành công. Lưu nội dung này thành .claude/hooks/after-edit.sh:

#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.py)
    ruff format "$FILE" >/dev/null 2>&1
    if ! ruff check "$FILE" >&2; then
      exit 2
    fi
    ;;
  *.sh)
    if ! shellcheck "$FILE" >&2; then
      exit 2
    fi
    ;;
esac

exit 0
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Yêu cầu Claude thêm một function thụt lề sai vào file Python, rồi mở file đó. File được format lại. Đây là cách xác nhận hook đã chạy, vì hook chạy thành công sẽ không hiển thị gì trong cuộc trò chuyện.

Exit 2 ở đây không hoàn tác thay đổi. PostToolUse chạy sau khi tool đã thực thi, nên thay đổi vẫn được ghi vào disk trong cả hai trường hợp. Exit 2 khiến output của ruff check được gửi lại cho model dưới dạng feedback, để model sửa lỗi vừa tạo thay vì tiếp tục. Đây là khác biệt giữa lỗi lint chỉ được phát hiện lúc commit và lỗi được agent tự sửa ngay trong cùng lượt xử lý.

Ở đây có hai giới hạn của matcher cần lưu ý. Edit|Write không thấy các file được thay đổi bởi shell command, trong khi Claude đủ thường xuyên ghi file qua Bash để khoảng trống này trở thành vấn đề thực tế. Để bao phủ từng lần gọi, hãy match cả Bash và cho script liệt kê các file đã thay đổi bằng git status --porcelain. Để bao phủ một lần cho mỗi lượt xử lý, hãy đặt bước scan vào một hook Stop thay thế.

Ví dụ 3: ghi log mọi lần gọi tool để audit

Matcher trống trên PostToolUse chạy sau mọi lần gọi tool thành công, ngoại trừ EndConversation. Gửi bản ghi vào system journal thay vì file trong thư mục home không khiến agent không thể truy cập bản ghi qua shell của chính nó: quyền truy cập phụ thuộc vào quyền của account. User có thể đọc journal riêng của chính mình, còn root và thành viên của systemd-journal, adm hoặc wheel có thể đọc mọi file journal:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
          }
        ]
      }
    ]
  }
}

Dùng journalctl -t claude-code -o cat | tail -n 5 để đọc lại. Nếu có quyền đọc bản ghi, bạn sẽ thấy mỗi lần gọi tool thành công ngoài EndConversation tương ứng với một dòng JSON, trong đó bản ghi mới nhất nằm cuối. Nếu không thấy gì, hãy kiểm tra cả quyền truy cập journal lẫn việc hook có chạy hay không; phần xử lý sự cố bên dưới sẽ đề cập đến hook.

Thêm cùng block này dưới PostToolUseFailure để ghi lại các lần gọi thất bại, vì PostToolUse chỉ chạy khi thao tác thành công và command thất bại thường mới là trường hợp đáng quan tâm. Lý do dùng logger thay vì append vào file trong thư mục home là quyền sở hữu: hook chạy với cùng user như shell của agent, nên bất kỳ thứ gì user đó có thể append thì cũng có thể truncate. systemd-journald ghi journal; việc ngăn xóa journal vẫn phụ thuộc vào quyền của account agent.

Thời gian một hook có thể chạy

Biểu đồDefault hook timeout in seconds, by hook type and event
Dữ liệu đằng sau biểu đồ này
[
  {
    "label": "command, http or mcp_tool hook",
    "default_timeout_seconds": 600
  },
  {
    "label": "agent hook",
    "default_timeout_seconds": 60
  },
  {
    "label": "prompt hook",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

Mặc định, một command hook được chạy trong 600 giây, tức 10 phút. Một số event rút ngắn thời gian này đáng kể. Các hook SessionEnd dùng chung ngân sách 1.5 giây cho toàn bộ hook, vì vậy tác vụ cleanup cuối session phải chạy nhanh. Tuy nhiên, nếu đặt timeout dài hơn cho một hook trong các file settings, ngân sách dùng chung sẽ tăng theo, tối đa 60 giây.

Một command, HTTP hoặc MCP tool hook chạy đồng bộ mà chạm timeout sẽ bị hủy và thường không tạo ra quyết định nào; với PreModelSwitch, timeout sẽ chặn thao tác chuyển đổi. Với một PreToolUse guardrail, timeout thường cho phép tool call tiếp tục vào permission flow thông thường; riêng trên Windows sẽ áp dụng ngoại lệ nêu trên khi onFailure chưa được set. Vì lý do đó, hãy giữ các script guardrail ngắn. Từ release 2.1.295, bạn có thể đảo ngược mặc định này trên hook command hoặc http bằng "onFailure": "block". Thiết lập này biến timeout, crash hoặc exit code không mong đợi thành block, nhưng không có tác dụng với Stop, SubagentStop, TaskCompleted, TeammateIdle hoặc background command hook. Với các tác vụ chạy chậm mà không cần chờ, chẳng hạn gửi log đến một nơi khác, hãy set "async": true để hook chạy trong background mà không làm tool call bị chậm lại.

Hooks, rules file, skill và MCP server

Bốn thành phần này thường bị nhầm lẫn vì đều thay đổi cách một agent hoạt động. Chỉ một thành phần trong số đó không còn là đề xuất.

Rules file (`CLAUDE.md hoặc một file bên dưới .claude/rules/`) là văn bản được nạp vào context của model. Nó định hình hành vi nhưng không thực thi được điều gì. Khi đặt cạnh một cuộc hội thoại dài, một diff lớn và yêu cầu mới từ user, một dòng trong đó có thể bị bỏ qua. Đây là cơ chế thông thường khiến agent bỏ qua các instruction bạn đã ghi lại.

Skill là một thư mục chứa instruction và script mà model nạp khi đánh giá skill đó phù hợp. Việc đánh giá này chính là mục đích của skill, đồng thời cũng là giới hạn của nó: model vẫn là thành phần quyết định. Có thể thấy cả hai mặt trong một skill như Ponytail, giúp agent hướng đến thay đổi nhỏ nhất nhưng vẫn hoạt động, vì nó định hình cách xử lý toàn bộ task theo cách mà hook không thể làm được, và chỉ hoạt động khi model chọn nạp nó.

MCP (model context protocol) server cung cấp cho model các tool mới để gọi. Nó mở rộng phạm vi mà agent có thể truy cập. Nó không khiến agent tự động sử dụng bất kỳ thứ gì, đồng thời đây là một process riêng mà bạn phải vận hành, bản thân việc đó cũng là một công việc riêng: xem cách chạy MCP server trên VPS.

Hook là thành phần duy nhất trong bốn thành phần này chạy mà không cần model lựa chọn. Dùng rules file cho một preference và dùng skill cho một procedure mà model phải làm theo khi phù hợp. Dùng hook cho bước bắt buộc phải xảy ra mỗi lần, hoặc cho việc tuyệt đối không được xảy ra. Phần so sánh chi tiết hơn, bao gồm trường hợp skill phù hợp hơn rules file, có trong bài so sánh skill, MCP và rules file.

Plugin là cách đóng gói, không phải cơ chế thứ năm. Nó gom các hook và skill vào một unit có thể cài đặt, nhờ đó team có thể triển khai cùng một guardrail lên mọi máy: xem cách Claude Code plugin hoạt động.

Quyết định bảo mật trên VPS dùng chung

Hook là code do agent kích hoạt và chạy dưới user đã khởi động Claude Code. Nó kế thừa quyền truy cập file và environment của user đó. Trên laptop, đây là vấn đề về workflow. Trên VPS nơi agent chạy không cần giám sát, đây là vấn đề bảo mật gồm 4 phần thực tế.

Hook trong repository là code mà bạn không viết. .claude/settings.json được commit, vì vậy việc clone repository và bắt đầu session bên trong đó có thể đăng ký các hook đi kèm repository. Trong session tương tác, Claude Code yêu cầu xác nhận project hook qua workspace trust dialog cho thư mục đó. Điều này có nghĩa chấp nhận trust là thời điểm bạn quyết định chạy các hook này. Hãy đọc block hooks trước. Session claude -p hoặc SDK, là cách agent không cần giám sát thường chạy, không bao giờ hiển thị dialog đó và xem thư mục là đáng tin cậy, nên hook của repository sẽ chạy mà không hỏi. Hãy review các file .claude/ trước khi viết script dùng với nó, hoặc chạy bằng --settings '{"disableAllHooks": true}'.

Hook nhìn thấy toàn bộ tool input. Audit hook ghi log tool_input sẽ ghi mọi argument của mọi command vào log, bao gồm cả token tình cờ xuất hiện trên command line. Khi đó log cần được bảo vệ giống như secret, và đây là một phần của vấn đề rộng hơn: giữ secret ngoài tầm với của AI agent.

Hook có thể ghi vào context của model. stdout dạng plain text từ hook SessionStart hoặc UserPromptSubmit chạy thành công sẽ được thêm vào conversation. Hook lấy text từ bên ngoài, issue tracker hoặc log file rồi pipe vào sẽ đưa text không đáng tin cậy cho model như thể chính bạn đã nhập text đó. Hook chuyển tiếp ghi chú từ một Claude Code session khác trên cùng VPS cũng làm điều tương tự. Output của agent này không đáng tin hơn issue tracker. Hãy xem stdout đó là input thay vì output.

Privilege mới là cơ chế kiểm soát thực sự. Chạy agent bằng một user riêng không có privilege, chỉ có các rule sudo cần thiết. Deny PreToolUse vẫn hữu ích và vốn được thiết kế theo hướng best effort: tài liệu tham chiếu cũng nói như vậy về filter if và yêu cầu bạn dùng permission system khi cần hard deny. Permission rule và account mà process chạy dưới đó mới là những phần vẫn có hiệu lực khi chịu áp lực.

Có một thuộc tính đúng trong mọi permission mode. Hook PreToolUse chạy trước bước kiểm tra permission mode trong mọi permission mode, vì vậy hook trả về deny sẽ block tool ngay cả dưới bypassPermissions. Hook có thể siết chặt những gì permission rule cho phép. Chúng không thể nới lỏng các rule đó. Ngoại lệ là mod. Trên máy không có managed settings và không có file managed-mcp.json, trong session không đăng nhập qua /login vào gói Team hoặc Enterprise, mod đã cài đặt xử lý tool.check có thể approve một call mà hook PreToolUse của bạn đã block. Khi có managed settings, file managed-mcp.json hoặc /login của Team hoặc Enterprise làm credential cho session, call bị hook PreToolUse block mặc định vẫn bị block, bất kể hook đến từ settings file nào. Session chạy bằng API key hoặc CLAUDE_CODE_OAUTH_TOKEN dài hạn, là cách nhiều server vận hành, được xem là chưa đăng nhập ngay cả khi đã lưu thông tin login. Hãy kiểm tra Claude Code mod có thể thay đổi những gì trước khi cài mod trên server.

Vì sao hook của tôi không chạy?

Hãy kiểm tra lần lượt theo thứ tự này. Mỗi bước nêu triệu chứng bạn sẽ thực sự thấy.

  • Chạy /hooks và kiểm tra xem hook có xuất hiện dưới event bạn mong đợi không. Hook không xuất hiện trong menu thường có nghĩa là file settings bị lỗi cú pháp JSON, vì không được dùng dấu phẩy ở cuối và comment, hoặc file không nằm trong một trong sáu vị trí ở trên.
  • So khớp matcher chính xác với tên tool. Matcher phân biệt chữ hoa chữ thường, nên "bash" không bao giờ khớp với tool Bash.
  • Chạy script thủ công với input mẫu như trong ví dụ 1 ở trên. Exit code không đúng với dự kiến là lỗi trong script; hãy kiểm tra cả stdout, vì JSON hợp lệ vẫn có thể cung cấp quyết định cho các event như PreToolUse.
  • Thông báo jq: command not found có nghĩa là máy đó đang thiếu jq. command not found đối với script của bạn có nghĩa là path không được resolve, vì vậy hãy dùng ${CLAUDE_PROJECT_DIR} hoặc path tuyệt đối. Nếu script hoàn toàn không chạy, có thể script chưa có quyền thực thi.
  • Hook in ra JSON hợp lệ nhưng không có gì xảy ra. Trên macOS và Linux, hook dạng shell chạy qua sh -c trong shell non-interactive, nhưng một số cấu hình vẫn source profile của bạn, chẳng hạn BASH_ENV trỏ đến ~/.bashrc. Nếu profile đó in banner, banner sẽ được thêm vào trước JSON. Khi đó stdout không còn bắt đầu bằng {, nên Claude Code đọc toàn bộ nội dung đó dưới dạng plain text và bỏ qua quyết định. Vì hook exit với mã 0 nên transcript không hiển thị lỗi. Trong hầu hết event, nội dung đó chỉ đi vào debug log; riêng UserPromptSubmit, UserPromptExpansion, SessionStart và PostModelSwitch, nó được thêm vào context của model, bao gồm cả banner. Hãy bọc mọi echo trong profile để lệnh đó chỉ chạy trong shell interactive.
  • Vẫn chưa xử lý được: khởi động session bằng claude --debug-file /tmp/claude.log và chạy tail -f /tmp/claude.log trong terminal thứ hai. Debug log ghi lại hook nào đã match, từng hook trả về exit code nào, cùng toàn bộ nội dung chúng ghi vào stdout và stderr.

FAQ

Sự khác nhau giữa hook của Claude Code và instruction trong CLAUDE.md là gì?

Instruction CLAUDE.md là văn bản trong context của model. Vì vậy, nó phải cạnh tranh sự chú ý với cuộc hội thoại và request hiện tại, đồng thời model có thể cân nhắc instruction đó cùng với các nội dung này. Hook là một shell command mà Claude Code chạy tại một thời điểm cố định trong vòng đời của nó. Vì vậy, hook được thực thi mỗi khi event tương ứng xảy ra, bất kể model đã quyết định gì. Dùng instruction cho một tùy chọn. Dùng hook cho một bước bắt buộc phải luôn thực hiện hoặc một hành động tuyệt đối không được thực hiện.

Làm cách nào để ngăn Claude Code chạy một shell command cụ thể?

Đăng ký hook PreToolUse với matcher Bash đọc command từ .tool_input.command, ghi lý do vào stderr rồi thoát với mã 2. Claude Code hủy lệnh gọi và hiển thị lý do của bạn cho model. Việc này xảy ra trước khi kiểm tra permission mode, nên quy tắc deny vẫn có hiệu lực ngay cả trong mode bypassPermissions. Pattern matching trên chuỗi command chỉ là một biện pháp guardrail, không phải ranh giới bảo mật, vì cùng một command có thể được viết theo dạng mà pattern không khớp. Do đó, hãy kết hợp nó với permission rules và một account không có quyền nâng cao.

Hook của tôi in JSON hợp lệ nhưng không có gì xảy ra. Tại sao?

Kiểm tra shell profile để tìm nội dung được in trước JSON. Trên macOS và Linux, hook không có field args sẽ chạy qua sh -c. Trong các cấu hình vẫn source profile của bạn, chẳng hạn BASH_ENV trỏ đến ~/.bashrc, profile in banner sẽ đưa banner vào stdout trước JSON. Vì output không còn bắt đầu bằng {, Claude Code coi toàn bộ output là plain text và bỏ qua quyết định. Do hook đã thoát với mã 0 nên transcript cũng không hiển thị lỗi. Bọc mọi echo trong profile bằng kiểm tra interactive shell, sau đó xác nhận đã sửa bằng cách đọc debug log từ claude --debug-file /tmp/claude.log.

Chạy hook của Claude Code trên shared server có an toàn không?

Hook chạy với tư cách user đã khởi động Claude Code và dùng permission của user đó. Vì vậy, hook có thể thực hiện mọi thao tác mà account này được phép thực hiện. Hai thói quen sau giúp giảm phần lớn rủi ro: chạy agent bằng một account không có quyền nâng cao dành riêng cho agent, với chính sách sudo giới hạn; đồng thời đọc block hooks của mọi repository trước khi chấp nhận workspace trust dialog hoặc chạy claude -p trong đó, vì project hook được đặt trong .claude/settings.json và mode -p không bao giờ hiển thị dialog này. Đặt "disableAllHooks": true trong settings file để tắt hook, ngoại trừ managed hook cần setting này ở cấp managed. Setting false của project có thể override setting true của user.

Bài viết này có hữu ích không?