Quan sát và an toàn

Kit theo dõi mức fan-out subagent và lượng tool output của mỗi phiên Claude Code, và chặn commit lộ secret hoặc chạm nhầm branch deploy. Ba mảng này chạy nền, bạn chỉ đọc kết quả hoặc xử lý khi bị chặn.

Khi nào dùng

Xem zenify observe report khi bạn muốn biết một phiên đã fan-out bao nhiêu subagent và tiêu tốn bao nhiêu tool output. Cài statusline khi bạn muốn thấy các số đó ngay trong Claude Code thay vì chạy lệnh riêng.

Chạy zenify secret-scan trước khi push một branch có file cấu hình hoặc script mới. CI của mọi repo public đã chạy lệnh này cho bạn.

zenify up và hook SessionStart tự gắn git-guard khi thiếu. Chạy zenify guard install (hoặc zenify doctor --fix) khi zenify doctor báo mục git-guard hỏng, hoặc sau khi bạn sửa tay <workspace>/.claude/settings.local.json. git-guard nằm ở file này nên chỉ chạy khi session mở ở gốc workspace.

Các bước

Quan sát số liệu phiên, và hai chốt chặn an toàn

Lệnh

zenify observe report

Cờ	Ý nghĩa
--json	In JSON thay cho bảng.

zenify observe report

Kết quả là một bảng theo phiên, phiên hoạt động gần nhất hiện trước. Dữ liệu đến từ hai hook observe-count và observe-meter mà zenify up đã cài.

zenify observe statusline

Claude Code gọi lệnh này qua key statusLine trong ~/.claude/settings.json. Dòng statusline gồm các đoạn, ẩn khi trống: model, phần trăm ngữ cảnh, số dispatch subagent, lượng tool output và chi phí.

zenify observe statusline install

Cờ	Ý nghĩa
--segment	Chỉ in hai đoạn của kit, số dispatch và tool output, để ghép vào statusline sẵn có.
--force (của install)	Đè statusline hiện có.

Claude Code chỉ cho phép một statusline. Lệnh install chỉ ghi khi key statusLine còn trống; đã có statusline khác thì lệnh từ chối và gợi ý ghép đoạn bằng --segment, hoặc đè bằng --force.

zenify secret-scan

zenify secret-scan .

Mỗi finding in ra một dòng gồm file, số dòng, tên rule và giá trị đã che, không in secret nguyên văn. Có finding thì lệnh kết thúc lỗi để CI đỏ. Không truyền đường dẫn, lệnh quét thư mục hiện tại.

zenify guard install

zenify guard install

Lệnh đăng ký hook PreToolUse với matcher Bash trỏ tới zenify git-guard, và gỡ mục cũ nếu còn. Chạy lại khi đã có cấu hình, lệnh chỉ báo đã sẵn và không ghi gì. Danh sách branch deploy đọc từ .claude/deploy-branches của từng repo.

Nguồn bằng chứng cho agent

Khi điều tra một triệu chứng trên staging hay production, các skill /znf:fix, /znf:hotfix, /znf:scout, /znf:gate, /znf:service-integration và /znf:explain-plan cùng đọc một tài liệu tham chiếu chung, _shared/evidence-sources.md (nằm trong internal/plugin/assets/znf/skills/_shared/). Tài liệu này nêu thứ tự tra cứu theo triệu chứng (log, trace, metric, zenify db-read/redis-read, PostHog), cách chuyển từ nguồn này sang nguồn khác, các ngõ cụt đã đo, giới hạn kích thước output và việc phải làm khi một nguồn không có. Phần về role dev trên production lấy danh sách lệnh từ bảng quyền của chính kit, nên khớp với broker cùng phiên bản (xem giới hạn dev ở trang broker); broker cũ hơn hoặc mới hơn kit có thể áp danh sách khác, khi đó nâng cấp cả hai lên cùng phiên bản. Agent không tự gõ tên công cụ hay mã định danh từ trí nhớ mà đọc từ tài liệu này.

Bước đầu tiên của tài liệu là đọc danh mục dịch vụ giám sát. zenify catalog [id] [--prd|--stg] in ra stdout dạng YAML các uid datasource Grafana và tên app trong Loki, service trong Tempo, metric Prometheus của một dịch vụ; lệnh thoát mã 5 khi broker hoặc danh mục chưa được cấu hình (khi đó agent quay về các bước khám phá bằng list_datasources và list_loki_label_values), mã 2 khi id không có trong danh mục. zenify catalog drift [--prd|--stg] so danh mục với tên đang có thật trong Loki và Prometheus trong 7 ngày qua, Tempo trong 72 giờ qua, in bảng UNLISTED/MISSING/ERROR và thoát mã 6 khi có lệch, mã 0 khi khớp, mã 5 khi chưa có danh mục. Agent chỉ báo chỗ lệch cho người dùng, không tự sửa danh mục. Phía host broker bật tính năng này theo mục danh mục dịch vụ.

Tóm tắt route và trace: zenify obs

Khi cần biết "route này đang chậm hay lỗi?" hoặc "trace này hỏng ở đâu?", agent chạy zenify obs trước khi tự viết truy vấn Tempo và Loki. Broker gọi Grafana thay agent, gộp kết quả và trả về một bản tóm tắt nhỏ. Lệnh có hai chế độ, chọn đúng một, và phải kèm đúng một trong --prd/--stg:

• zenify obs <id> --route "<METHOD path>" [--since 6h]: thống kê route của service <id> (số lượng, tốc độ, p50/p95/p99, tỉ lệ lỗi, phân bố status), vài trace chậm nhất và trace lỗi làm mẫu, số dòng log lỗi. --since mặc định 24h, tối đa 48h.
• zenify obs --trace <trace-id>: tóm tắt một trace (span gốc, các service, nhóm span, span lỗi) cùng các dòng log nhắc tới trace id. Trace id dài 1 đến 32 ký tự hex; broker tìm log theo cả dạng 32 ký tự lẫn dạng gốc.

Giới hạn cần biết:

• Broker che PII theo mẫu: số điện thoại, email, địa chỉ IPv4, bearer token, JWT và mật khẩu nhúng trong URL. Chữ tự do như tên người, địa chỉ không có mẫu nên không được che. Vì vậy output vẫn không được dán vào spec, PR hay báo cáo, theo quy tắc dữ liệu ở trên.
• Response tối đa 32 KB, mỗi dòng log tối đa 500 byte; khi broker cắt bớt, lệnh ghi một dòng obs: response truncated (…) ra stderr.
• Staging không có thống kê: với --stg, phần thống kê route có thể vắng (kèm ghi chú TraceQL metrics unavailable on this env) hoặc lệnh báo service chưa có tên Tempo trên staging; khi đó dựa vào trace mẫu và log.
• Mã thoát 5 nghĩa là broker chưa bật obs; agent quay về các tool Grafana trực tiếp.
• Tempo từ chối truy vấn metrics trải từ 3 giờ trở lên: zenify obs tự chia khoảng thời gian, còn khi gọi tool MCP trực tiếp thì agent phải tự chia. Tempo có thể bỏ các số 0 đầu của trace id; khi tự tìm log, agent tìm theo cả dạng 32 ký tự đã đệm lẫn dạng ngắn gốc.

Phía host broker bật obs cùng khối catalog:, xem mục danh mục dịch vụ.

Kết quả

Artifact	Nội dung
Bảng hoặc JSON của observe report	Số dispatch subagent và tool output theo phiên
Đoạn statusline	Model, % ngữ cảnh, dispatch, tool output, chi phí
Output secret-scan	Danh sách finding file:line:rule, giá trị che
Hook git-guard	Chặn commit, push, merge vào branch trong .claude/deploy-branches, kể cả khi gọi qua alias git -c alias.<tên>=push <tên>
Hook git-guard (lệnh lồng)	Theo vào bash -c, sh -c, zsh -c và eval (tối đa 3 tầng), bỏ các wrapper ở đầu lệnh, rồi áp các luật dưới đây. Chuỗi lồng có biến (bash -c "… $X") và shell đọc script từ stdin (heredoc, pipe vào sh, -s) được coi là không phân tích được
Hook git-guard (force push)	Chặn force push (--force, -f, cờ gộp như -uf, --force-with-lease, --force-if-includes, refspec +<branch>) trên mọi branch
Hook git-guard (merge PR)	Chặn gh pr merge và gh api … PUT …/merge
Hook git-guard (stack)	Chặn gh stack merge, gh stack unstack và gh stack delete (trừ khi có --local), gh stack link, gh stack alias (lệnh tắt nó cài, mặc định gs, guard không nhận ra), gh api tới đường dẫn merge-async hoặc /stacks/<n>/unstack, và gh stack init, gh stack add với tên deploy branch. Merge, gỡ và ghép stack là việc của người
Hook git-guard (worktree)	Chặn wt rm --force, wt rm -f, zenify wt rm --force hoặc -f, và git worktree remove --force hoặc -f
Hook git-guard (secret)	Chặn đọc <workspace>/.zenify/.env qua Bash, kể cả qua redirect (<, 3<, <<<); chặn lệnh đọc cả thư mục (grep, rg, find, tar, cp, cat, …) nhắm vào chính thư mục .zenify, và mọi lệnh nhắm vào một glob trong đó (.zenify/*) hay một file .env trong đó. Thư mục .zenify/data-runs/ (bản ghi dry-run và log ghi của zenify data run) không tính: cat .zenify/data-runs/*.log được chạy. git-guard bung dấu ngoặc nhọn ngoài dấu nháy (.zenif{y,}, {x..z..1}) như shell trước khi xét, và chặn luôn lệnh bung ra quá 1024 từ; trong data-runs, từ có .., glob ở phần thư mục, hay glob chạm tới symlink trỏ về .zenify/.env không được miễn, và ln tạo link trong .zenify bị chặn. Vẫn cho zenify db-read …, zenify redis-read …, `zenify env list
Hook git-guard (không phân tích được)	Chặn lệnh không phân tích được mà chứa từ khoá nguy hiểm
Hook tmp-check (đầu phiên)	In khối <tmp-check> khi thư mục tạm của user (trên macOS là getconf DARWIN_USER_TEMP_DIR, không phải $TMPDIR) hoặc /tmp có từ 50.000 mục trở lên, hoặc đọc không xong trong 3 giây. In thêm một dòng khi máy đã chạy liên tục từ 7 ngày. Không có gì bất thường thì không in gì. macOS dọn thư mục tạm khi khởi động; với khoảng 1,3 triệu thư mục do test bỏ lại, máy treo ngay ở bước đó và không vào được cả Safe Mode. Thấy cảnh báo thì tìm prefix bị rò rỉ và sửa test trước khi khởi động lại
Thông báo chặn	Lệnh chỉ người được làm (force push, merge PR, stack, wt rm --force, push vào deploy branch, --manifest cho db-read/redis-read, lệnh không phân tích được có từ khoá merge/force/stack) kết thúc bằng Dừng và báo người dùng; không thử biến thể.; commit hay merge trên deploy branch chỉ agent sang worktree riêng (wt new <slug>); chặn đọc .zenify/.env chỉ agent sang zenify db-read, redis-read và zenify data run

Lưu ý

Các luật của git-guard áp ở mọi chế độ quyền, kể cả bypass và auto. Với force push và merge PR, bạn tự chạy lệnh đó bằng ! ở dấu nhắc của Claude Code khi thật sự cần; agent không có đường nào khác. Đọc production thì agent dùng zenify db-read --prd, xem Đọc dữ liệu thật. Ghi vào database thật thì agent dùng zenify data run: bắt buộc dry-run trước, credential ghi chỉ do broker cấp theo role (production chỉ lead), xem Dùng credential broker.

Git-guard là lớp chặn sai sót, không chặn được agent cố tình lách, ví dụ một script tự mở file .zenify/.env.

Không chặn: lệnh được ghép lúc chạy, ví dụ tên file nằm trong một biến; grep -r chạy từ thư mục gốc workspace; đường dẫn .zenify/.env nhắc tới bên trong thân heredoc của một script; cd không đứng đầu lệnh, ví dụ true; cd <repo> && git push …, vì git-guard chỉ đổi thư mục gốc theo cd chạy đầu tiên.

Một binary vừa build nằm trong cây thư mục có thể tạo finding giả cho secret-scan. Xóa binary trước khi quét. Khi git-guard chặn một lệnh, hãy báo lại thay vì tìm cách vòng qua.

Git-guard và secret-scan chặn khi rule khớp, không phải advisory. Cách chúng phản ứng khi chính công cụ gặp lỗi xem ở Gate fail-open.

Xem thêm

/reference/cli/zenify_observe_report, /reference/cli/zenify_observe_statusline_install, /reference/cli/zenify_secret-scan, /reference/cli/zenify_guard_install, Gate fail-open, Đọc dữ liệu thật