Hooks và quyền riêng tư: agent bị chặn đọc gì, và vì sao chặn chưa phải là đủ

Bài 7/20 trong bộ onboarding AgentKit v3. Đọc khoảng 9 phút.

Hook là mấy đoạn code chạy trước hoặc sau mỗi hành động của agent: trước khi đọc file, trước khi chạy lệnh shell, lúc mở session, lúc nén context... AgentKit dùng hook để làm hai việc: nhắc agent làm việc có kỷ luật và chặn agent đụng vào thứ nhạy cảm.

Bài này liệt kê hook có trong kit, cách bật/tắt, và quan trọng nhất: giới hạn thật của lớp bảo vệ này.

1/ Danh sách hook ✅

Kit core (cài cùng mọi kit)

Kit Engineer thêm

agent-behavior-linter, cook-after-plan-reminder, plan-format-kanban, precompact-capture (ghi lại trạng thái trước khi context bị nén), session-init, session-state, subagent-init, team-context-inject, và nhóm usage-* theo dõi mức dùng.

2/ Bật, tắt hook ✅

Mỗi hook có một công tắc trong preference:

ak config prefs set hooks.descriptive-name false
ak config prefs set hooks.descriptive-name true

Lời khuyên: đừng tắt privacy-block và secret-output-guardrail. Mấy hook nhắc nhở thì tuỳ khẩu vị, thấy phiền cứ tắt.

3/ Privacy guard hoạt động ra sao ✅

Khi agent định đọc một file nhạy cảm:

1. Hook từ chối lần đầu, kèm câu hỏi cho bạn.

2. Bạn duyệt (trong Claude Code là một hộp chọn "Yes, approve access" hoặc "No, skip this file").

3. Agent thử lại với đánh dấu APPROVED:, lúc này mới đọc được.

Bản 3.0.0 vá thêm mấy đường lách mà tui gặp thật:

• Lần đầu đụng vào file nhạy cảm qua shell cũng bị chặn, không chỉ qua tool Read.

• Lệnh pipe hoặc bọc (kiểu cat .env | grep KEY, bash -c "cat .env") được soi để bắt việc đọc dotenv.

• Tool PowerShell trên Windows cũng được phủ.

4/ .akignore: danh sách "đừng đụng" của bạn ✅

Cú pháp y như .gitignore. ak đọc theo thứ tự:

1. <AGENTKIT_HOME>/.akignore (mặc định ~/.agentkit/.akignore) cho mọi project

2. <project>/.akignore

3. <project>/.agentkit/.akignore

Ví dụ:

# hợp đồng khách hàng
contracts/**
# dữ liệu thật
data/production/**
*.pem

Điểm tinh tế: rule ở cấp project cần được tin cậy (trust) trước khi có hiệu lực. ak lưu digest của file vào state/akignore-trust/. Tại sao? Vì nếu không, một repo lạ bạn vừa clone về có thể tự thêm .akignore để nới quy tắc. File đổi thì phải tin cậy lại.

5/ Giới hạn thật: đọc kỹ phần này ⚠️

Tui viết thẳng, vì tài liệu bảo mật mà chỉ khoe thì còn nguy hiểm hơn không có tài liệu:

Privacy guard là lớp hợp tác (cooperative), không phải hàng rào chống một model cố tình phá. Nó chặn được agent "lỡ tay", chặn được đa số prompt injection ngây thơ. Nhưng một model đủ quyết tâm, có quyền chạy shell tuỳ ý, vẫn có cách đi vòng. Muốn chắc ăn tuyệt đối thì secret không được nằm trên đĩa dạng plaintext. Đó là lý do có vault.

Trên Codex, privacy guard chưa phủ MCP và các tool đọc cục bộ. Theo bảng chứng nhận runtime v3.0.0. Nếu bạn dùng Codex với MCP server có quyền đọc file, hãy coi như guard không có ở đường đó.

Hook chỉ chạy khi runtime hỗ trợ hook. Mỗi runtime có mức hỗ trợ khác nhau. Claude Code là nơi hook đầy đủ nhất.

Vậy combo tui dùng hằng ngày:

1. Secret trong vault, không trong .env.

2. Privacy guard bật, để bắt những lần lỡ tay.

3. .akignore cho thư mục nhạy cảm của từng khách hàng.

4. Không cho agent chạy với quyền rộng hơn mức cần trên repo chứa dữ liệu thật.

6/ Kiểm tra nhanh

ak doctor

Doctor báo trạng thái hook và cấu hình liên quan. Muốn agent tự rà:

/ak-security quét project này tìm secret bị lộ và kiểm tra .akignore

Bài tiếp: Decision Layer: System One, Jev, Clef →

Nguồn

• Danh sách hook trong agentkit/kits/core và agentkit/kits/engineer (tag v3.0.0)

• Release note v3.0.0 (mục privacy guard: deny first sensitive shell access, piped/wrapped dotenv reads, PowerShell tool): https://github.com/bestagentkits/agentkit/releases/tag/v3.0.0

• Tài liệu .akignore và trust digest trong repo agentkit (tag v3.0.0)

• Ma trận chứng nhận runtime v3.0.0 (ghi chú Codex privacy guard)