Trang này được dịch từ tài liệu tiếng Anh. Lệnh, định danh và ví dụ giữ nguyên. Runtime 7.24.4 · SDK 2.6.7. Bản tiếng Anh

Hook vòng đời

Trạng thái: Đang hoạt động
Phạm vi: trạng thái hiện tại
Xem xét lần cuối: 2026-08-23 Chủ sở hữu: môi trường chạy ax-code

Hook vòng đời cho phép bạn chạy lệnh shell trên các sự kiện tác nhân mà không dựng lại môi trường chạy. Chúng bổ sung quy tắc quyền và hộp cát cô lập: hook là hiệu ứng phụ tất định (“luôn định dạng”, “không bao giờ force-push”), trong khi lời nhắc vẫn mang tính tham khảo.

Sự kiện

Bốn sự kiện vòng đời phiên (SessionStart, SessionEnd, PostCompact, Interrupt) và PostToolUseFailure chỉ để quan sát: chúng bắn rồi quên, không bao giờ chặn đường vòng đời, và tải của chúng chỉ mang id/lý do/dấu thời gian — không bao giờ văn bản hội thoại, bản tóm tắt, hay đầu ra công cụ. Phiên tác nhân con không bắn SessionStart (chúng đã hiện qua SubagentStop). SubagentStop bắn cho các con được cả task và task_parallel khởi động.

Phản hồi PostToolUse tới mô hình

Một hook PostToolUse có thể trả văn bản lại cho mô hình. Nó được nối vào kết quả công cụ bên trong một khối <hook_feedback event="PostToolUse">, sau đầu ra của chính công cụ; nó không bao giờ thay đầu ra và không bao giờ chặn.

• Mục cũ (không có protocol): stdout đã cắt của một hook thoát 0.
• Mục protocol: "claude-code": hookSpecificOutput.additionalContext, reason của một phán quyết {"decision": "block", "reason": "..."}, hoặc stderr khi hook thoát 2. Các lần thoát khác không phải không thì không đóng góp gì.

Phản hồi bị trần ở 4,000 ký tự mỗi hook và 8,000 ký tự mỗi lời gọi công cụ, nên một hook ồn không thể làm ngập ngữ cảnh. Đây là điều làm gói format-after-edit hữu ích: lời nhắc của nó giờ tới lượt kế tiếp của mô hình thay vì chỉ nằm trong nhật ký.

Các tên này ánh xạ tới bộ kích hoạt plugin nội bộ của AX Code (tool.execute.before / tool.execute.after) cộng hook lời nhắc, nén, tác nhân con và dừng cấp phiên. Các lời nhắc tiếp tục tổng hợp (lời nhắc agentRouting: "preserve" nội bộ) không bắn UserPromptSubmit.

Bật gói

Hook và plugin dự án thực thi mã do kho kiểm soát, nên .ax-code/hooks.json, .ax-code/plugin/ và plugin được cấu hình theo dự án bị tắt theo mặc định. Sau khi xem lại chúng, hãy chọn tham gia bên ngoài kho khi khởi động AX Code:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Rồi tạo .ax-code/hooks.json trong dự án của bạn:

{
  "packs": ["format-after-edit", "block-force-push", "require-tests-on-stop", "protect-env-files", "log-bash-commands"]
}

Gói chính thức (≥5)

Hook tùy chỉnh:

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "echo running bash",
      "blockOnFailure": false
    }
  ]
}

Giao thức dây Claude Code (bật tùy chọn)

Nếu bạn đã có hook viết cho Claude Code, một mục có thể chọn giao thức dây Claude Code bằng "protocol": "claude-code":

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "my-claude-code-hook.sh",
      "protocol": "claude-code"
    }
  ]
}

Với các sự kiện có thể chặn (PreToolUse, UserPromptSubmit), các mục đã chọn tham gia được giải mã bằng ngữ nghĩa Claude Code thay cho kiểm tra blockOnFailure:

• Thoát 2 chặn hành động; stderr của hook được hiện làm lý do. Stdout sai dạng vẫn chặn (an toàn khi lỗi).
• Thoát 0 với JSON stdout {"permissionDecision": "allow"|"deny"|"ask", "reason"?}: allow tiếp tục; deny chặn với reason; ask tạm dừng lời gọi công cụ trên một lời nhắc quyền hook tương tác hiện lý do (mặc định "hook requested user confirmation"). Lời nhắc chỉ tương tác: không quy tắc always, cấp wildcard, hay tự phê duyệt tự chủ nào có thể trả lời nó, và một lần chạy không tương tác từ chối nó, điều mà mô hình thấy như một từ chối quyền thông thường. Một hook sau trả lời deny thắng ask trước đó. UserPromptSubmit không có lời gọi công cụ để gắn lời nhắc, nên ask vẫn chặn ở đó. Dạng Claude Code lồng {"hookSpecificOutput": {"permissionDecision": "...", "permissionDecisionReason": "..."}} được chấp nhận như một bí danh.
• Mọi lần thoát khác là lỗi không chặn (được ghi nhật ký, hành động tiếp tục).

Các sự kiện chỉ quan sát bỏ qua bộ giải mã hoàn toàn — chúng không bao giờ có thể chặn. Các mục không có trường protocol hành xử đúng như trước.

Biến môi trường sẵn có cho lệnh hook:

• HOOK_EVENT — các sự kiện PreToolUse, PostToolUse, PostToolUseFailure, Stop, UserPromptSubmit, PreCompact, SubagentStop, SessionStart, SessionEnd, PostCompact và Interrupt
• HOOK_TOOL — id công cụ
• HOOK_SESSION_ID
• HOOK_ARGS_JSON — đối số công cụ JSON
• HOOK_ARGS_STDIN=1 — đối số JSON đầy đủ luôn có trên stdin; HOOK_ARGS_JSON rỗng với tải lớn hơn 32 KiB
• HOOK_PACK — tên gói khi áp dụng

Tiến trình con hook thừa hưởng một phiên bản đã làm sạch của môi trường AX Code. AX Code giữ các biến nền tảng và công cụ thông thường, nhưng gỡ các tên giống bí mật, URL mang thông tin xác thực, trợ giúp thông tin xác thực như SSH_AUTH_SOCK, và biến tiêm tiến trình như NODE_OPTIONS. Các biến giao thức HOOK_* ở trên được thêm sau khi làm sạch và luôn sẵn có.

Hook cũ được tin hoàn toàn, cần thông tin xác thực môi trường xung quanh, có thể khôi phục hành vi trước bên ngoài kho:

AX_CODE_HOOKS_FULL_ENV=1 AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Cửa thoát này phơi mọi biến môi trường cho mọi hook đã bật. Một kho không thể yêu cầu nó qua .ax-code/hooks.json; chỉ dùng sau khi xem lại mọi hook và gói.

Ghi chú bảo mật: việc làm sạch môi trường giảm phơi bày thông tin xác thực xung quanh nhưng không hộp cát hóa lệnh hook. Hook vẫn là mã shell tùy ý, có thể đọc tệp truy cập được và dùng mạng máy chủ. Hãy coi chúng là mã đáng tin và xem lại mọi hook và gói đã bật.

Quan hệ với cô lập

Hook không thay hộp cát. Hãy dùng:

1. Cô lập ứng dụng cho ranh giới ghi/mạng có thể mang đi
2. Cô lập hệ điều hành (backend "auto" mặc định) cho hộp cát bash được nhân thực thi khi có
3. Hook cho hiệu ứng phụ chính sách và các chặn cứng như force-push

Xem Chế độ hộp cát và SECURITY.md.