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ó 55 entry Hook. Con số này là inventory của artifact, không phải 55 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.

Context firewall và agent behavior linter

Hook context-firewall chạy trước các lệnh Bash, PowerShell, Read, Grep và Glob, rồi ước tính lượng nội dung mà lệnh đó có thể trả về. Hook cho phép lệnh thông thường, cảnh báo mà không chặn, hoặc chặn lệnh và nêu một cách thay thế có giới hạn:

Khi cùng một thao tác đã bị cảnh báo chạm tới lần can thiệp thứ ba trong một session, cảnh báo trở thành chặn. Mỗi lần can thiệp được ghi vào một bản ghi theo session có giới hạn, với giá trị credential đã được che. Firewall luôn fail-open: nếu Hook gặp lỗi ngoài dự kiến, lệnh vẫn được thực hiện.

Hook agent-behavior-linter quan sát hoạt động tool trong session và, tại Stop, có thể báo cáo các pattern mà nó chứng minh được từ hoạt động đó: đọc lại một tệp không thay đổi, chạy lại một lệnh thất bại với cùng lỗi, search rộng lặp lại, output tool lớn mà không tệp nào thay đổi, và chạy toàn bộ test suite sau một thay đổi chỉ liên quan tài liệu. Mỗi phát hiện nêu điều đã quan sát, việc nên làm thay thế và nguyên tắc tương ứng trong ak:context-engineering. Linter chỉ giữ số liệu tổng hợp có giới hạn trong trạng thái riêng theo session, không bao giờ chặn lệnh tool và không in báo cáo khi không có phát hiện nào.

Cả hai Hook đều bật theo mặc định. Để tắt một Hook, đặt hooks.context-firewall hoặc hooks.agent-behavior-linter thành false; xem Quản lý preference của Hook.

Phê duyệt truy cập tệp nhạy cảm

Hook privacy-block chạy trước các lệnh gọi Read, Write, Edit, Bash và PowerShell, bảo vệ các tệp dotenv như .env và .env.local, tệp credentials, secrets.yaml hoặc secret.yml, tệp .pem và .key, cùng SSH private key. Lần truy cập đầu tiên vào một path như vậy bị từ chối trên mọi runtime và mọi đường công cụ, kể cả path nằm trong lệnh shell và các chỉnh sửa Codex apply_patch đi qua matcher Edit và Write. Việc kiểm tra lệnh shell cũng bao gồm những gì một shell đọc stdin (sh, bash -s, iex) chạy từ một đoạn pipeline phía trước, đoạn script truyền vào [scriptblock]::Create hoặc InvokeScript, lệnh chạy qua Start-Process hoặc xargs, và các wrapper có option nhận giá trị như sudo -u, wsl -d hoặc timeout -s. Tên tệp dotenv được ghép bằng phép nối chuỗi PowerShell, khớp qua glob bắt đầu bằng dấu chấm, hoặc viết dưới dạng NTFS alternate data stream hay tên ngắn 8.3 của Windows cũng được nhận diện. Các tệp mẫu như .env.example, .env.sample và .env.template vẫn được phép, và một biểu thức mã nguồn như process.env.API_KEY không bị coi là path tệp.

Thông báo từ chối nêu rõ thao tác (read, write hoặc edit) và yêu cầu agent hỏi bạn qua khả năng ask-user của runtime: AskUserQuestion trên Claude Code, và request_user_input trên Codex khi có, nếu không thì một câu hỏi chat thông thường rồi kết thúc lượt. Các runtime khác nhận câu hỏi chat thông thường.

1. Agent hỏi bạn. Bạn phê duyệt hoặc từ chối một lần truy cập vào path đã nêu.
2. Agent thử lại một lần. Sau khi được phê duyệt, agent lặp lại đúng lệnh gọi đó với mỗi path được bảo vệ có tiền tố APPROVED:. Hook bỏ tiền tố trước khi công cụ chạy, nên công cụ thấy path thật.
3. Phê duyệt được dùng hết. Phê duyệt gắn với session, path đã chuẩn hóa và thao tác, chỉ dùng cho một lệnh gọi và hết hạn sau 15 phút. Trên Claude Code, lần thử lại đã được phê duyệt vẫn hiện permission prompt gốc với đúng lệnh gọi.

Tiền tố APPROVED: không có lần từ chối trước đó, lần thử lại thứ hai, phê duyệt đã hết hạn, hoặc lần chạy không có định danh session đều bị từ chối. Vì vậy lần chạy non-interactive fail closed: không ai trả lời được, nên agent tiếp tục mà không dùng tệp đó. Khi bạn từ chối, agent được yêu cầu tiếp tục mà không dùng tệp và không truy cập nó qua công cụ hay lệnh khác.

Trên Codex, atom Read bị bỏ, nên Hook chỉ bảo vệ đường shell và chỉnh sửa; các thao tác đọc qua MCP và local function tool không được bảo vệ. AgentKit báo điều này trong output cài đặt, như một phần của ghi chú matcher bị thu hẹp. Hook bật theo mặc định; đặt hooks.privacy-block thành false để tắt, như mô tả trong Quản lý preference của Hook.

Tham chiếu secret trong lệnh gọi công cụ

Hook secrets-inject chạy trước các lệnh gọi Bash, PowerShell và WebFetch. Khi một lệnh shell hoặc URL fetch chứa tham chiếu ${secret:NAME}, Hook hỏi ak secrets resolve để lấy giá trị đã lưu và thay thế trong bộ nhớ, nhờ đó model có thể soạn lệnh gọi mà không nhìn thấy credential. Chỉ Bash.command, PowerShell.command và WebFetch.url được quét; nội dung tệp và prompt được giữ nguyên. Grant ak secrets cho binary agent đang gọi quyết định giá trị có được giải phóng hay không, và grant bị giới hạn bằng --allow-host còn kiểm tra đích fetch.

Mọi lỗi đều chặn lệnh gọi công cụ thay vì chuyển nguyên văn tham chiếu đi, bao gồm thiếu grant, tên không hợp lệ hoặc giá trị có ký tự đặc biệt của shell khi đi vào một lệnh Bash hoặc PowerShell. Riêng với lệnh PowerShell, giá trị chứa ,, @ hoặc dấu nháy typographic cũng bị từ chối, vì PowerShell sẽ đọc chúng thành dấu tách mảng, splat hoặc dấu nháy; hãy truyền giá trị như vậy qua biến môi trường. Hook không ghi bản sao nào của giá trị, nhưng input đã thay thế vẫn tới process của công cụ và mọi thứ runtime ghi lại cho một lệnh gọi đã thực thi, chẳng hạn transcript. Hãy coi giá trị đã giải phóng là có mặt trên host và rotate khi cần.

Claude Code và Grok đăng ký Hook cho Bash|PowerShell|WebFetch, còn Codex thu hẹp thành Bash. Hỗ trợ Cursor cho Hook này chưa được xác lập trong bản phát hành này.

Liveness cho cập nhật nền tự động

Hook session-heartbeat.cjs đăng ký trên SessionStart, UserPromptSubmit, Stop và SessionEnd. Nó ghi một marker theo session dưới AgentKit home để cập nhật nền opt-in bỏ qua project đang có agent session sống, và gỡ marker đó ở SessionEnd. Tại SessionStart, nó cũng in một dòng thông báo cho kết quả cập nhật nền chưa được xem, xác nhận bằng ak update --status --ack --json. Hook không bao giờ chặn session và tự thoát 0 ngay cả khi lỗi.

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à bốn 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|PowerShell trở thành Write|Edit|Bash, bỏ Read và PowerShell nhưng giữ privacy-block.cjs hoạt động cho các atom được hỗ trợ. Các thao tác đọc trên Codex qua MCP và local function tool không được bảo vệ; xem Phê duyệt truy cập tệp nhạy cảm.
• Bash|PowerShell|Read trở thành Bash, bỏ PowerShell và Read nhưng giữ scout-block.cjs hoạt động cho Bash.
• Bash|PowerShell|Read|Grep|Glob trở thành Bash, bỏ PowerShell, Read, Grep và Glob nhưng giữ context-firewall.cjs hoạt động cho Bash.
• Bash|PowerShell|WebFetch trở thành Bash, bỏ PowerShell và WebFetch nhưng giữ secrets-inject.cjs hoạt động cho Bash.

Các đăng ký agent-behavior-linter.cjs trên PostToolUse, PreCompact và Stop được projection mà không bị thu hẹp.

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 Hook groups not projected 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.

Codex home do wrapper quản lý chỉ được liên kết leaf hooks cuối cùng tới ~/.codex/hooks canonical của user đã resolve, bằng symlink POSIX hoặc directory junction trên Windows. AgentKit dùng path canonical đó cho command đã translate, thao tác ghi, rollback và ownership. Parent có link và target không canonical vẫn bị từ chối.

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.

Để bật, tắt hoặc khôi phục soft-preference của một Hook mà không đổi việc cài đặt của nó, hãy xem Quản lý preference của Hook.

Để 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.

Nhóm Hook chưa được project có thể là unsupported hoặc được harness bridge trì hoãn. Đọc hooksDeferred riêng với nhóm unsupported; deferred không đồng nghĩa không được hỗ trợ vĩnh viễn.