Hook của Engineer và hỗ trợ theo runtime

Hook của Engineer bổ sung automation xoay quanh thao tác với tool, prompt, ranh giới session và handoff. Hook có thể trả về hướng dẫn, yêu cầu phê duyệt, dừng một thao tác không an toàn hoặc quá rộng, hay cập nhật trạng thái workflow có giới hạn. Bạn không gọi Hook như Skill hoặc command; runtime đã chọn sẽ gọi các handler được hỗ trợ khi event tương ứng xảy ra.

Package Engineer đã resolve có 44 entry Hook. Con số này là inventory của artifact, không phải 44 behavior độc lập. Nó bao gồm manifest của Hook, event handler, thư viện hỗ trợ dùng chung, cùng helper về trạng thái và statusline riêng của Engineer. Một handler có thể tham gia nhiều event, còn tệp hỗ trợ có thể không bao giờ tự chạy.

Event graph đang hoạt động

Graph đang hoạt động được tổ chức theo kết quả thay vì số lượng tệp trong package:

Những kết quả này hỗ trợ workflow Engineer; chúng không tự phê duyệt plan, commit, merge, deploy hay phát hành công việc thay bạn.

Path đã cấu hình khi bắt đầu session

Handler SessionStart resolve tùy chọn path của project trước khi export môi trường mà workflow Engineer sử dụng. Giá trị tương đối của paths.docs hoặc paths.plans được resolve dưới project base của session. Giá trị tuyệt đối được export nguyên vẹn dưới dạng CK_DOCS_PATH hoặc CK_PLANS_PATH, thay vì được join vào path của project. Export này cung cấp các vị trí đã cấu hình cho Skill; các bề mặt plan, journal và dashboard Go native yêu cầu riêng paths.plans tương đối theo project và fallback về plans/ khi giá trị là path tuyệt đối.

Projection theo runtime

Các nhãn dưới đây mô tả nội dung trở thành active:

• Emitted nghĩa là AgentKit ghi một artifact native đang hoạt động.
• Translated nghĩa là AgentKit ánh xạ behavior được hỗ trợ sang event model native của runtime.
• Dropped nghĩa là runtime không biểu diễn được behavior nên behavior đó không hoạt động.
• Narrowed nghĩa là handler vẫn hoạt động nhưng chỉ với tập con có thể biểu diễn của matcher ban đầu.
• Sidecar-preserved nghĩa là nội dung package được giữ lại để hỗ trợ hoặc truy vết nguồn gốc, nhưng bản thân nó không phải feature runtime đang hoạt động.

Statusline Engineer chỉ dành cho Claude Code. Codex và Cursor không có statusline chỉ vì package chứa tệp hỗ trợ statusline.

Hỗ trợ một phần trên Codex

Codex có event model và matcher model nhỏ hơn Claude Code. Engineer projection một group bị drop hoàn toàn và hai matcher bị thu hẹp:

• Matcher PostToolUse Agent|Task|TodoWrite|TodoRead với handler session-state.cjs bị drop hoàn toàn. Các đăng ký Stop và SubagentStop riêng vẫn còn.
• Read|Write|Edit|Bash trở thành Write|Edit|Bash, bỏ Read nhưng giữ privacy-block.cjs hoạt động cho các atom được hỗ trợ.
• Bash|Read trở thành Bash, bỏ Read nhưng giữ scout-block.cjs hoạt động cho Bash.

Drop hoặc narrow không làm cài đặt thất bại. Output cho người dùng liệt kê chúng dưới Hooks dropped (unsupported on this target) và Hook matchers narrowed (some tool matches unsupported on this target). JSON dùng các field tùy chọn hooksDropped, droppedHookSummaries, hookMatchersNarrowed và narrowedHookSummaries. Hãy xem chúng là disclosure về capability, không phải bằng chứng toàn bộ automation Engineer bị thiếu.

Lời nhắc plan chỉ được export trên wildcard Stop, không phải SubagentStop. Khi không có plan đang hoạt động, hook trả mã 0 với stdout rỗng. Khi phù hợp, hook emit JSON chỉ với success field hợp lệ, có dạng {"continue":true,"systemMessage":"..."}, và luôn fail-open.

Hỗ trợ chạy Hook trên Windows

Trên Windows, Hook .cjs hợp lệ nằm trong Codex home đã resolve có thể chạy từ path thông thường chứa khoảng trắng. AgentKit emit một shim .cmd sibling được quản lý và tham chiếu shim đó từ cấu hình Hook đã translate. Shim là output do AgentKit sở hữu và tham gia lifecycle refresh cùng uninstall thông thường.

Hỗ trợ này có giới hạn rõ ràng. Path có khoảng trắng nhưng nằm ngoài Codex home, path chứa metacharacter của cmd.exe, tên shim không phải ASCII hoặc argument được bake không an toàn hay không phải ASCII vẫn không được hỗ trợ và sẽ tạo cảnh báo. Argument rỗng có cảnh báo riêng; shim cùng path và cùng nội dung được deduplicate, còn nội dung xung đột giữ shim đầu tiên rồi cảnh báo. Path không cần shim tiếp tục dùng command trực tiếp. Không sửa thủ công shim hoặc cấu hình Hook đã được tạo.

Chẩn đoán bề mặt Claude Code đang hoạt động

ak doctor --adapter claude-code --json discover các bề mặt Hook Claude Code đã bật theo scope và delivery mode, thay vì xem tệp package là bằng chứng một Hook đang hoạt động. Với bản cài native ở scope project và người dùng, check hook_registration so sánh expectation đã cài với đăng ký đang hoạt động trong settings.json và xác minh các entrypoint được tham chiếu. Với bản cài plugin, check này kiểm tra manifest Hook đang hoạt động và các entrypoint của manifest. Hook bị tắt qua AgentKit được loại khỏi expectation native.

Check hook_log đọc log gắn với từng bề mặt native hoặc plugin đã discover. Một bề mặt active mới chưa có log vẫn được xem là healthy; đăng ký, manifest hoặc entrypoint bị thiếu được báo kèm scope và delivery mode. Hãy dùng kết quả này để xác định bề mặt bị ảnh hưởng trước khi refresh hoặc cài lại Kit.

Ownership và lifecycle

Đăng ký Hook ở scope project và người dùng có thể cùng tồn tại. Với cấu hình Codex global dùng chung, AgentKit merge các đăng ký do nó sở hữu trong khi giữ lại Hook của người dùng, field bên ngoài và đăng ký thuộc Kit khác. Entry đã bị sửa hoặc xung đột sẽ được giữ lại hay báo cáo thay vì bị ghi đè âm thầm.

Metadata của Hook do AgentKit sở hữu tham gia rollback. Khi không còn Kit nào sở hữu một cấu trúc do AgentKit tạo, quá trình dọn dẹp sẽ loại bỏ cấu trúc rỗng đó nhưng giữ lại cấu trúc có sẵn hoặc từ nguồn bên ngoài. Đây là cải thiện độ tin cậy của lifecycle, không phải bảo đảm bảo mật hay quyền xóa nội dung tùy ý khỏi tệp cấu hình Hook dùng chung.

Refresh và uninstall chỉ tác động lên nội dung được ghi nhận là do AgentKit sở hữu, không phải mọi Hook trong runtime. Hãy review preview của thao tác và snapshot khôi phục trước khi áp dụng thay đổi lifecycle. Không xóa runtime home hoặc toàn bộ tệp cấu hình Hook dùng chung để sửa lỗi.

Khắc phục sự cố an toàn

1. Đọc disclosure của cài đặt. Kiểm tra cả heading drop và narrow hoặc các field JSON tương ứng trước khi kết luận toàn bộ Hook graph thất bại.
2. Xác nhận target và scope. Bản cài ở project và người dùng là riêng biệt, và runtime có thể nạp một bản khác với bản bạn dự kiến.
3. Chạy health check cho target. Dùng ak doctor --adapter claude-code --json cho Claude Code hoặc ak doctor --adapter codex --json cho Codex, rồi kiểm tra các check được báo cáo thay vì giả định có tệp đồng nghĩa Hook đang hoạt động.
4. Kiểm tra phân loại path trên Windows. Path .cjs hợp lệ trong Codex home có thể dùng shim được quản lý; dạng path bên ngoài hoặc không an toàn sẽ cảnh báo.
5. Dùng đúng route lifecycle. Preview refresh hoặc uninstall, giữ nội dung đã được người dùng sửa và kiểm tra mọi snapshot khôi phục trước khi áp dụng thay đổi.

Để xem flag cài đặt chính xác, hãy đọc Cài đặt Kit và tham chiếu ak kit init. Để xem khác biệt capability giữa các adapter, hãy đọc Runtime adapter. Nếu việc cài đặt hoặc discovery vẫn chưa rõ, hãy tiếp tục với Lỗi cài Kit và Runtime không tìm thấy Skill hoặc Agent.