Cách hooks hoạt động

ClaudeKit Hooks

Hãy xem hooks như lớp guard rails bao quanh Claude Code.

Hook là một script nhỏ lắng nghe một lifecycle moment, đọc context hiện tại, rồi giúp Claude Code tiếp tục theo cách an toàn hơn hoặc hữu ích hơn.

16 hooks 5 categories

Diagram mô tả ClaudeKit hooks như lớp guard rails: user intent đi vào Claude Code lifecycle events, hooks đọc JSON context, rồi allow, block, inject context, hoặc lưu session state.

Hiểu flow trước khi đọc tên từng hook

Mọi ClaudeKit hook đều đi theo cùng một pattern đơn giản. Khi pattern này rõ, từng hook bên dưới sẽ dễ hiểu hơn.

Một moment xảy ra

Claude Code bắt đầu session, nhận prompt, chuẩn bị dùng tool, sửa file, hoặc hoàn thành task.

Claude gửi context

Hook nhận JSON context: tên event, tool target, working directory, task hiện tại, và session state liên quan.

Hook kiểm tra rule

ClaudeKit so context đó với project rules, cài đặt project, ignored paths, privacy patterns, hoặc workflow state.

Claude tiếp tục có guard rail

Hook có thể cho tiếp tục, chặn việc rủi ro, inject context, hoặc lưu state cho bước sau.

Không phải prompt template

Prompt nói model nên làm gì. Hook có thể đọc context và enforce rule trước khi công việc tiếp tục.

Bốn kết quả cần nhớ

Allow

Cho việc an toàn tiếp tục.

Block

Chặn truy cập rủi ro hoặc hành động không an toàn.

Inject

Thêm rules, team context, hoặc reminders.

Remember

Lưu session state hữu ích.

Danh sách hooks

ClaudeKit hooks theo vai trò

Đọc từng nhóm từ trên xuống. Mỗi hook có ba tín hiệu nhanh: mặc định đang bật hay tắt, có thể chặn thao tác không, và cách tắt khi bạn không cần.

Trạng thái mặc định

Bật nghĩa là hook đang chạy sẵn. Tắt nghĩa là hook có sẵn nhưng project mới không tự chạy, chỉ bật khi bạn opt-in.

Tắt an toàn

Mở từng hook để copy đoạn .claude/.ck.json nhỏ nhất nhằm tắt hook đó.

Nếu hook bị lỗi

Fail-open nghĩa là hook lỗi thì Claude bỏ qua hook đó và chạy tiếp. Bạn chỉ mất guard, reminder, context, hoặc state update tương ứng.

Hook lỗi có làm hỏng flow không?

Thường là không. Nếu hook crash ngoài ý muốn, ClaudeKit fail-open: bỏ qua hook đó để công việc tiếp tục. Phần bị mất chỉ là guard, reminder, context, hoặc state mà hook phụ trách. Riêng policy block có chủ đích như privacy, scout, simplify, hoặc artifact gates vẫn có thể chặn khi rule thật sự match.

Vòng đời Session

Khởi tạo, lưu trữ và theo dõi trạng thái session xuyên suốt vòng đời.

4 hooks

session-init.cjs Chuẩn bị context của workspace khi Claude Code bắt đầu, để các hooks sau biết project, config, và environment. Engineer Kit + Marketing Kit Mặc định tắt File hook vẫn có sẵn, nhưng project mới không tự bật nhóm hook inject context này. Thêm context Đưa thêm context hữu ích cho main agent hoặc subagents. Chi tiết

Triggers: SessionStart (startup/resume/clear/compact)
Ví dụ đơn giản: Bạn mở Claude Code trong một repo. Hook này nhận diện project, config, package manager, và branch để các hook sau hiểu workspace.
Cách tắt: Project mới đã tắt sẵn. Nếu project đã bật lại command thủ công, set flag này về false hoặc xoá entry trong settings.

json · .claude/.ck.json

{ "hooks": { "session-init": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Claude chỉ có thể thiếu phần context hoặc awareness mà hook này định thêm.
Cách hook này hoạt động: Khởi tạo session với project detection, load config, và setup environment. Kích hoạt khi startup, resume, clear, và compact.

session-state.cjs Theo dõi plan, todo, và branch hiện tại để session có thể phục hồi sau compact hoặc handoff. Engineer Kit Mặc định tắt File hook vẫn có sẵn, nhưng project mới không tự bật nhóm hook inject context này. Lưu state Ghi lại tiến độ để bước sau khôi phục hoặc tổng hợp. Chi tiết

Triggers: PostToolUse (Task/TaskCreate/TaskUpdate/TodoWrite) Stop SubagentStop
Ví dụ đơn giản: Sau compact hoặc handoff, ClaudeKit có thể khôi phục plan và todo đang làm thay vì xem session như mới hoàn toàn.
Cách tắt: Project mới đã tắt sẵn. Nếu project đã bật lại command thủ công, set flag này về false hoặc xoá entry trong settings.

json · .claude/.ck.json

{ "hooks": { "session-state": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Chỉ có progress/state của hook này có thể không được ghi cho bước sau.
Cách hook này hoạt động: Lưu và khôi phục tiến trình session qua các lần compact. Lưu plan, todo items, và trạng thái branch.

usage-quota-cache-refresh.cjs Refresh quota ở nền để statusline có dữ liệu mà không làm chậm mỗi prompt. Engineer Kit Mặc định tắt File hook vẫn có sẵn, nhưng project mới không tự bật nhóm hook inject context này. Thêm context Đưa thêm context hữu ích cho main agent hoặc subagents. Chi tiết

Triggers: SessionStart (startup/resume/clear/compact) UserPromptSubmit PostToolUse (Task/TaskCreate/TaskUpdate/TodoWrite)
Ví dụ đơn giản: Statusline có thể hiện context quota từ cache mà không bắt mỗi prompt chờ kiểm tra quota mới.
Cách tắt: Project mới đã tắt sẵn. Nếu project đã bật lại command thủ công, set flag này về false hoặc xoá entry trong settings.

json · .claude/.ck.json

{ "hooks": { "usage-quota-cache-refresh": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Claude chỉ có thể thiếu phần context hoặc awareness mà hook này định thêm.
Cách hook này hoạt động: Giữ cache usage quota cho statusline. Throttle thông minh: 60s cho prompt, 300s cho tool events.

usage-context-awareness.cjs Đóng vai trò bật/tắt usage awareness khi project muốn dùng context về quota. Engineer Kit + Marketing Kit Mặc định tắt File hook vẫn có sẵn, nhưng project mới không tự bật nhóm hook inject context này. Thêm context Đưa thêm context hữu ích cho main agent hoặc subagents. Chi tiết

Triggers: (optional setting)
Ví dụ đơn giản: Nếu project bật usage awareness, hook này cho phép context quota xuất hiện. Nếu chưa bật, nó im lặng.
Cách tắt: Project mới đã tắt sẵn. Nếu project đã bật lại command thủ công, set flag này về false hoặc xoá entry trong settings.

json · .claude/.ck.json

{ "hooks": { "usage-context-awareness": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Claude chỉ có thể thiếu phần context hoặc awareness mà hook này định thêm.
Cách hook này hoạt động: Công tắc tuỳ chọn cho usage-quota-cache-refresh. Chỉ thêm context quota khi được bật trong .claude/.ck.json.

Inject Context

Inject rules, thông tin environment, và team context vào prompts và subagents.

3 hooks

dev-rules-reminder.cjs Đưa các quy tắc quan trọng của project vào mỗi prompt để agent không quên conventions nội bộ. Engineer Kit + Marketing Kit Mặc định tắt File hook vẫn có sẵn, nhưng project mới không tự bật nhóm hook inject context này. Thêm context Đưa thêm context hữu ích cho main agent hoặc subagents. Chi tiết

Triggers: UserPromptSubmit
Ví dụ đơn giản: Bạn yêu cầu sửa UI. Hook đưa project rules vào lại context, ví dụ đọc README trước và không revert thay đổi không liên quan.
Cách tắt: Project mới đã tắt sẵn. Nếu project đã bật lại command thủ công, set flag này về false hoặc xoá entry trong settings.

json · .claude/.ck.json

{ "hooks": { "dev-rules-reminder": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Claude chỉ có thể thiếu phần context hoặc awareness mà hook này định thêm.
Cách hook này hoạt động: Inject session info, development rules, modularization reminders, và plan context vào mỗi prompt.

subagent-init.cjs Đưa cho mỗi subagent context tối thiểu cần thiết thay vì đổ toàn bộ session vào. Engineer Kit + Marketing Kit Mặc định tắt File hook vẫn có sẵn, nhưng project mới không tự bật nhóm hook inject context này. Thêm context Đưa thêm context hữu ích cho main agent hoặc subagents. Chi tiết

Triggers: SubagentStart
Ví dụ đơn giản: Một review subagent bắt đầu. Nó nhận task và context repo gọn, không nhận toàn bộ cuộc hội thoại chính.
Cách tắt: Project mới đã tắt sẵn. Nếu project đã bật lại command thủ công, set flag này về false hoặc xoá entry trong settings.

json · .claude/.ck.json

{ "hooks": { "subagent-init": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Claude chỉ có thể thiếu phần context hoặc awareness mà hook này định thêm.
Cách hook này hoạt động: Inject context tối giản (~200 tokens) vào subagents dùng env vars từ SessionStart.

team-context-inject.cjs Giúp các agent teammate biết ai đang làm gì, giảm việc làm trùng trong team-mode. Engineer Kit Mặc định tắt File hook vẫn có sẵn, nhưng project mới không tự bật nhóm hook inject context này. Thêm context Đưa thêm context hữu ích cho main agent hoặc subagents. Chi tiết

Triggers: SubagentStart
Ví dụ đơn giản: Trong team run, một frontend teammate thấy file nào teammate khác đang phụ trách, giảm việc sửa trùng.
Cách tắt: Project mới đã tắt sẵn. Nếu project đã bật lại command thủ công, set flag này về false hoặc xoá entry trong settings.

json · .claude/.ck.json

{ "hooks": { "team-context-inject": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Claude chỉ có thể thiếu phần context hoặc awareness mà hook này định thêm.
Cách hook này hoạt động: Inject thông tin đồng đội và task summary khi spawn Agent Team teammates. Non-blocking, fail-open.

Chất lượng Code

Enforce naming conventions, nhắc simplify code, và định dạng plan.

3 hooks

descriptive-name.cjs Chặn tên file mới quá mơ hồ và nhắc agent dùng kebab-case mô tả rõ hơn. Engineer Kit + Marketing Kit Mặc định bật Đang chạy sẵn trong bộ guard rails mặc định. Chỉ nhắc Thêm nhắc nhở hoặc cảnh báo, rồi để flow tiếp tục. Chi tiết

Triggers: PreToolUse (Write)
Ví dụ đơn giản: Nếu agent định tạo `utils.ts`, hook nhắc dùng tên rõ hơn như `format-campaign-countdown.ts`.
Cách tắt: Set hook flag về false trong .claude/.ck.json. Muốn bật lại thì xoá dòng đó hoặc set lại true.

json · .claude/.ck.json

{ "hooks": { "descriptive-name": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Chỉ có nhắc nhở hoặc cảnh báo của hook này có thể bị thiếu.
Cách hook này hoạt động: Enforce đặt tên file theo kebab-case mô tả rõ ràng khi tạo file mới.

simplify-gate.cjs Cảnh báo hoặc chặn ship khi diff quá lớn và cần simplify trước. Engineer Kit Mặc định tắt Có sẵn nhưng chỉ chạy sau khi bạn chủ động bật gate. Có thể chặn Khi bật, nếu rule thật sự match thì hook có thể chặn action hiện tại. Chi tiết

Triggers: UserPromptSubmit
Ví dụ đơn giản: Trước khi ship, một diff quá lớn có thể bị cảnh báo hoặc chặn để agent simplify thay đổi trước.
Cách tắt: Gate mặc định đang tắt. Nếu đã bật thủ công, tắt hook flag hoặc set simplify.gate.enabled=false. Bypass khẩn cấp: CK_SIMPLIFY_DISABLED=1.

json · .claude/.ck.json

{ "hooks": { "simplify-gate": false }, "simplify": { "gate": { "enabled": false } } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, hook được bỏ qua để flow tiếp tục. Nếu rule thật sự match, hook vẫn có thể chặn action đó vì đây là guard rail đúng.
Cách hook này hoạt động: Gate opt-in (mặc định gate.enabled=false). Hard-block ship/merge/pr/deploy/publish và soft-warn commit/finalize/release khi working tree có diff lớn chưa simplify (400 LOC / 8 file / 200 LOC một file). Bypass qua env CK_SIMPLIFY_DISABLED=1 hoặc .ck.json hooks.simplify-gate=false.

plan-format-kanban.cjs Giữ plan dễ đọc bằng cách bắt các link chỉ dùng tên file làm text. Engineer Kit Mặc định tắt File hook vẫn có sẵn, nhưng project mới không tự bật nhóm hook inject context này. Chỉ nhắc Thêm nhắc nhở hoặc cảnh báo, rồi để flow tiếp tục. Chi tiết

Triggers: PostToolUse (Edit/Write/MultiEdit)
Ví dụ đơn giản: Nếu link trong plan chỉ ghi `task-1.md`, hook nhắc dùng text dễ đọc để plan dễ scan hơn.
Cách tắt: Project mới đã tắt sẵn. Nếu project đã bật lại command thủ công, set flag này về false hoặc xoá entry trong settings.

json · .claude/.ck.json

{ "hooks": { "plan-format-kanban": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Chỉ có nhắc nhở hoặc cảnh báo của hook này có thể bị thiếu.
Cách hook này hoạt động: Cảnh báo khi plan.md dùng tên file làm link text thay vì tên dễ đọc.

Bảo mật & An toàn

Chặn truy cập vào file nhạy cảm và thư mục bị hạn chế.

2 hooks

privacy-block.cjs Chặn file nhạy cảm như .env hoặc credentials cho tới khi user phê duyệt rõ ràng. Engineer Kit + Marketing Kit Mặc định bật Đang chạy sẵn trong bộ guard rails mặc định. Có thể chặn Khi bật, nếu rule thật sự match thì hook có thể chặn action hiện tại. Chi tiết

Triggers: PreToolUse (Bash/Glob/Grep/Read/Edit/Write)
Ví dụ đơn giản: Một tool định đọc `.env`. Hook chặn lượt đọc đó và yêu cầu user phê duyệt rõ ràng trước.
Cách tắt: Set hook flag về false trong .claude/.ck.json. Muốn bật lại thì xoá dòng đó hoặc set lại true.

json · .claude/.ck.json

{ "hooks": { "privacy-block": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, hook được bỏ qua để flow tiếp tục. Nếu rule thật sự match, hook vẫn có thể chặn action đó vì đây là guard rail đúng.
Cách hook này hoạt động: Chặn truy cập file nhạy cảm (.env, credentials). Cần user phê duyệt để tiếp tục.

scout-block.cjs Bảo vệ folder bị ignore hoặc hạn chế bằng .ckignore trước khi tools đọc hoặc sửa. Engineer Kit + Marketing Kit Mặc định bật Đang chạy sẵn trong bộ guard rails mặc định. Có thể chặn Khi bật, nếu rule thật sự match thì hook có thể chặn action hiện tại. Chi tiết

Triggers: PreToolUse (Bash/Glob/Grep/Read/Edit/Write)
Ví dụ đơn giản: Một tool định xem thư mục bị `.ckignore` bỏ qua. Hook chặn trước khi agent đọc hoặc sửa path đó.
Cách tắt: Set hook flag về false trong .claude/.ck.json. Muốn bật lại thì xoá dòng đó hoặc set lại true.

json · .claude/.ck.json

{ "hooks": { "scout-block": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, hook được bỏ qua để flow tiếp tục. Nếu rule thật sự match, hook vẫn có thể chặn action đó vì đây là guard rail đúng.
Cách hook này hoạt động: Chặn truy cập thư mục theo .ckignore patterns. Dùng gitignore-spec matching.

Workflow & Teams

Điều phối planning, task tracking, và team agent collaboration.

4 hooks

cook-after-plan-reminder.cjs Khi planning xong, nhắc agent chuyển sang implementation bằng command tiếp theo phù hợp. Engineer Kit Mặc định tắt File hook vẫn có sẵn, nhưng project mới không tự bật nhóm hook inject context này. Chỉ nhắc Thêm nhắc nhở hoặc cảnh báo, rồi để flow tiếp tục. Chi tiết

Triggers: SubagentStop (Plan)
Ví dụ đơn giản: Khi planning agent hoàn tất, hook chỉ bước tiếp theo sang implementation kèm path của plan vừa tạo.
Cách tắt: Project mới đã tắt sẵn. Nếu project đã bật lại command thủ công, set flag này về false hoặc xoá entry trong settings.

json · .claude/.ck.json

{ "hooks": { "cook-after-plan-reminder": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Chỉ có nhắc nhở hoặc cảnh báo của hook này có thể bị thiếu.
Cách hook này hoạt động: Nhắc chạy /ck:cook sau khi Plan subagent hoàn thành. Xuất plan path cho session mới.

task-completed-handler.cjs Ghi nhận task đã hoàn thành để tiến độ vẫn rõ giữa nhiều agent và các bước sau. Engineer Kit Mặc định tắt Dùng cho Agent Teams; single-agent bình thường không chạy hook này. Lưu state Ghi lại tiến độ để bước sau khôi phục hoặc tổng hợp. Chi tiết

Triggers: TaskCompleted
Ví dụ đơn giản: Một teammate đánh dấu task xong. Hook ghi lại tiến độ để agent tiếp theo biết phần nào đã hoàn thành.
Cách tắt: Project mới đã tắt sẵn. Nếu project đã bật lại command thủ công, set flag này về false hoặc xoá entry trong settings.

json · .claude/.ck.json

{ "hooks": { "task-completed-handler": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Chỉ có progress/state của hook này có thể không được ghi cho bước sau.
Cách hook này hoạt động: Log task completions và inject progress context khi agents đánh dấu task hoàn thành.

teammate-idle-handler.cjs Khi một teammate sắp idle, đưa việc còn lại cho nó hoặc để run tiếp tục gọn gàng. Engineer Kit Mặc định tắt Dùng cho Agent Teams; single-agent bình thường không chạy hook này. Chỉ nhắc Thêm nhắc nhở hoặc cảnh báo, rồi để flow tiếp tục. Chi tiết

Triggers: TeammateIdle
Ví dụ đơn giản: Một teammate sắp idle. Hook có thể giao việc còn lại hoặc cho nó dừng gọn gàng.
Cách tắt: Project mới đã tắt sẵn. Nếu project đã bật lại command thủ công, set flag này về false hoặc xoá entry trong settings.

json · .claude/.ck.json

{ "hooks": { "teammate-idle-handler": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, flow vẫn tiếp tục. Chỉ có nhắc nhở hoặc cảnh báo của hook này có thể bị thiếu.
Cách hook này hoạt động: Inject context về task còn trống khi teammate idle. Implementation hiện tại non-blocking và fail-open.

workflow-artifact-gate.cjs Kiểm tra review artifacts trước finalize hoặc ship-like actions để workflow không bỏ qua evidence. Engineer Kit Mặc định tắt Có sẵn nhưng chỉ chạy sau khi bạn chủ động bật gate. Có thể chặn Khi bật, nếu rule thật sự match thì hook có thể chặn action hiện tại. Chi tiết

Triggers: PreToolUse (finalize stage) manual CLI
Ví dụ đơn giản: Trước finalize, hook kiểm tra verification và review artifacts tồn tại để workflow không bỏ qua evidence.
Cách tắt: Mặc định đang tắt. Nếu đã bật thủ công, set hook flag hoặc workflow gate về false. Bypass khẩn cấp: CK_WORKFLOW_ARTIFACT_GATE_DISABLED=1.

json · .claude/.ck.json

{ "hooks": { "workflow-artifact-gate": false }, "workflowArtifactGate": { "enabled": false } }
Nếu hook này lỗi: Nếu crash ngoài ý muốn, hook được bỏ qua để flow tiếp tục. Nếu rule thật sự match, hook vẫn có thể chặn action đó vì đây là guard rail đúng.
Cách hook này hoạt động: Validate review artifacts của ck:fix/ck:cook (context-snippets, verification, review-decision, risk-gate) trước khi finalize và ship-like actions. Có thể bật trong .claude/.ck.json; fail-open khi crash.

Tìm hiểu thêm các built-in hooks của ClaudeKit tại ClaudeKit Documentation