failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/vi/built-in-policies.mdx

@@ -0,0 +1,853 @@
+---
+title: Chính sách tích hợp sẵn
+description: "Tất cả 39 chính sách tích hợp sẵn giúp bắt các lỗi phổ biến của agent"
+icon: shield
+---
+
+failproofai được cung cấp kèm 39 chính sách tích hợp sẵn giúp bắt các lỗi phổ biến của agent. Mỗi chính sách kích hoạt trên một loại sự kiện hook cụ thể và tên công cụ. Mười chín chính sách chấp nhận các tham số cho phép bạn điều chỉnh hành vi của chúng mà không cần viết code. Năm chính sách quy trình làm việc buộc phải thực hiện commit → push → PR → CI trước khi Claude dừng lại.
+
+---
+
+## Tổng quan
+
+Các chính sách được nhóm thành các danh mục:
+
+| Danh mục | Chính sách | Loại Hook |
+|----------|----------|-----------|
+| [Lệnh nguy hiểm](#lệnh-nguy-hiểm) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse |
+| [Lệnh cơ sở hạ tầng](#lệnh-cơ-sở-hạ-tầng) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse |
+| [Bí mật (sanitizer)](#bí-mật-sanitizer) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse |
+| [Môi trường](#môi-trường) | block-env-files, protect-env-vars | PreToolUse |
+| [Truy cập file](#truy-cập-file) | block-read-outside-cwd, block-secrets-write | PreToolUse |
+| [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse |
+| [Cơ sở dữ liệu](#cơ-sở-dữ-liệu) | warn-destructive-sql, warn-schema-alteration | PreToolUse |
+| [Cảnh báo](#cảnh-báo) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse |
+| [Trình quản lý gói](#trình-quản-lý-gói) | prefer-package-manager | PreToolUse |
+| [Quy trình làm việc](#quy-trình-làm-việc) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop |
+
+- **`block-`** — ngăn agent tiếp tục.
+- **`warn-`** — cung cấp bối cảnh bổ sung để agent có thể tự sửa lỗi.
+- **`sanitize-`** — xóa sạch dữ liệu nhạy cảm từ đầu ra công cụ trước khi agent nhìn thấy.
+
+### Không gian tên
+
+Mỗi chính sách tồn tại trong một vị trí `<namespace>/<name>`. Các chính sách tích hợp sẵn thuộc không gian tên **`failproofai/`** — ví dụ: `failproofai/sanitize-jwt`. Không gian tên ngăn chặn xung đột khi bạn cũng tải các chính sách tùy chỉnh hoặc của bên thứ ba có tên ngắn tương tự.
+
+Trong cấu hình của bạn, bạn có thể tham chiếu đến một chính sách tích hợp bằng tên ngắn hoặc tên đủ tiêu chuẩn; cả hai dạng đều phân giải thành cùng một chính sách:
+
+```json
+{
+  "enabledPolicies": [
+    "sanitize-jwt",
+    "failproofai/block-rm-rf"
+  ]
+}
+```
+
+Nếu tên không có `/`, failproofai coi nó thuộc không gian tên mặc định `failproofai`. Tên đã chứa `/` (ví dụ: `myorg/foo`, `custom/my-hook`) được giữ nguyên.
+- **`require-`** — chặn sự kiện Stop cho đến khi các điều kiện được đáp ứng.
+
+---
+
+<Tip>
+Mỗi chính sách hỗ trợ một trường `hint` tùy chọn trong `policyParams`. Gợi ý được nối thêm vào thông báo từ chối hoặc hướng dẫn mà Claude nhìn thấy, cung cấp hướng dẫn có thể thực hiện được mà không cần sửa đổi code chính sách. Hoạt động với các chính sách tích hợp sẵn, tùy chỉnh và quy ước. Xem [Cấu hình → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết.
+</Tip>
+
+---
+
+## Lệnh nguy hiểm
+
+Ngăn agent chạy các hoạt động khó hoàn tác hoặc có thể gây hại cho hệ thống chủ.
+
+### `block-sudo`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối bất kỳ lệnh `sudo` hoặc `doas` nào.
+
+Chặn một lệnh chạy một tệp nhị phân nâng cao quyền **ở vị trí lệnh**. Khớp là có cấu trúc hơn là văn bản: lệnh được chia thành các đoạn theo cách shell, gán tiền tố (`FOO=bar`), chuyển hướng và chạy với cờ của chúng (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) được bỏ qua, và tệp nhị phân kết quả được so sánh theo **tên cơ sở**. Do đó, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` và `bash -c "sudo …"` đều bị từ chối, và `doas` được coi là cùng một khả năng với tên khác.
+
+Vì nó neo trên vị trí lệnh thay vì từ xuất hiện ở bất kỳ đâu, nó **không** kích hoạt trên các lệnh chỉ đề cập đến nó — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, hoặc một thay thế `grep` chứa từ này đều chạy bình thường.
+
+<Warning>
+Điều này dừng lại cố gắng rõ ràng; nó không đóng lớp. Một agent có thể chạy shell tùy ý vẫn có thể đạt được nâng cao quyền gián tiếp — thông qua một biến (`S=sudo; $S …`), một pipe giải mã base64 hoặc một tập lệnh wrapper trên đĩa — vì không có kiểm tra chuỗi lệnh duy nhất nào có thể theo dõi những điều đó. Hãy coi đây là một hàng rào bảo vệ chống lại các lỗi và nâng cao quyền bình thường, chứ không phải như một ranh giới bảo mật chống lại một agent quyết tâm. Một ranh giới thực tế phải được thực thi dưới shell.
+</Warning>
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh chính xác được phép. Mỗi mục được so sánh với các token argv được phân tích cú pháp. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    }
+  }
+}
+```
+
+Với cấu hình này, `sudo systemctl status nginx` được phép, nhưng `sudo rm /etc/hosts` bị từ chối.
+
+<Note>
+Các mẫu được so sánh với các token được phân tích cú pháp, không phải chuỗi lệnh thô. Điều này ngăn chặn bypass thông qua các toán tử shell nối (ví dụ: `sudo systemctl status x; rm -rf /` không khớp với `sudo systemctl status *`).
+</Note>
+
+---
+
+### `block-rm-rf`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối `rm -rf`, `rm -fr` và các dạng xóa đệ quy tương tự.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | Các đường dẫn an toàn để xóa đệ quy (ví dụ: `/tmp`). |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-rm-rf": {
+      "allowPaths": ["/tmp", "/var/cache"]
+    }
+  }
+}
+```
+
+---
+
+### `block-curl-pipe-sh`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` và các mẫu tương tự.
+
+Không có tham số.
+
+---
+
+### `block-failproofai-commands`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối các lệnh sẽ gỡ cài đặt hoặc vô hiệu hóa failproofai (ví dụ: `npm uninstall failproofai`, `failproofai policies --uninstall`).
+
+Không có tham số.
+
+---
+
+### `block-self-pause`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối `failproofai config --pause`, tạm dừng thực thi cho một phiên. Tạm dừng là quyết định của con người — một agent có khả năng chạy nó có thể tắt mọi chính sách khác bằng một lệnh duy nhất.
+
+Hẹp hơn [`block-failproofai-commands`](#block-failproofai-commands) có mục đích, và không được bao phủ bởi nó: chính sách đó neo trên một ranh giới lệnh, do đó `npx -y failproofai config --pause` không khớp với nó, và vì rộng nên thường bị tắt để agent có thể chạy `failproofai audit`. `--resume` và `--status` được phép — cả hai đều không loại bỏ thực thi.
+
+Điều này dừng lại cố gắng trực tiếp, không phải toàn bộ lớp: một agent vẫn có thể đạt được trạng thái tương tự thông qua một bí danh hoặc tập lệnh wrapper. Đóng nó hoàn toàn yêu cầu tạm dừng không thể tiếp cận từ lệnh công cụ.
+
+Không có tham số.
+
+---
+
+## Lệnh cơ sở hạ tầng
+
+Ngăn agent mã hóa chạy CLI cơ sở hạ tầng hoặc kích hoạt đường ống CI/CD. Tất cả các chính sách trong danh mục này là **opt-in** (`defaultEnabled: false`) — các agent có nhu cầu hợp pháp để gọi `kubectl`, `terraform`, v.v. sẽ không bị gián đoạn trừ khi bạn bật chính sách. Khi bật, mọi lệnh gọi CLI được khớp bị từ chối trừ khi lệnh khớp với một mục trong `allowPatterns`.
+
+Ngữ pháp mẫu giống như [`block-sudo`](#block-sudo): các token được so sánh với argv được phân tích cú pháp, `*` là ký tự đại diện cho một token và bất kỳ lệnh nào chứa một toán tử shell độc lập (`&&`, `||`, `|`, `;`) hoặc token với siêu ký tự shell nhúng bị từ chối trước khớp danh sách cho phép để ngăn chặn bypass tiêm.
+
+### `block-kubectl`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối bất kỳ lệnh gọi `kubectl` nào.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh kubectl được phép. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-kubectl": {
+      "allowPatterns": ["kubectl get *", "kubectl describe *", "kubectl logs *"]
+    }
+  }
+}
+```
+
+Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply -f deploy.yaml` bị từ chối.
+
+---
+
+### `block-terraform`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối bất kỳ lệnh gọi `terraform` hoặc `tofu` (OpenTofu) nào.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh terraform/tofu được phép. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-terraform": {
+      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-aws-cli`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối bất kỳ lệnh gọi CLI `aws` nào.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh aws CLI được phép. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-aws-cli": {
+      "allowPatterns": ["aws s3 ls *", "aws sts get-caller-identity"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gcloud`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối bất kỳ lệnh gọi CLI `gcloud` (Google Cloud) nào.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh gcloud được phép. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-gcloud": {
+      "allowPatterns": ["gcloud auth list", "gcloud config list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-az-cli`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối bất kỳ lệnh gọi CLI `az` (Azure) nào.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh az CLI được phép. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-az-cli": {
+      "allowPatterns": ["az account show", "az group list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-helm`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối bất kỳ lệnh gọi `helm` nào.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh helm được phép. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-helm": {
+      "allowPatterns": ["helm list", "helm status *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gh-pipeline`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối các lệnh con `gh` CLI sau đây thay đổi trạng thái hoặc kích hoạt đường ống:
+
+- `gh workflow run`, `gh workflow enable`, `gh workflow disable`
+- `gh run rerun`, `gh run cancel`
+- `gh pr merge`
+- `gh release create`, `gh release delete`
+- `gh cache delete`
+- `gh secret set`, `gh secret delete`
+
+Các lệnh con `gh` chỉ đọc như `gh pr view`, `gh pr list`, `gh run list`, `gh release view` và `gh api repos/.../...` **không** được khớp bởi chính sách này — chúng thường cần thiết cho kiểm tra quy trình làm việc (bao gồm cả `require-ci-green-before-stop` của failproofai).
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Lệnh gọi tập lệnh cụ thể được phép mặc dù chúng sẽ bị từ chối. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-gh-pipeline": {
+      "allowPatterns": ["gh run rerun *"]
+    }
+  }
+}
+```
+
+---
+
+## Bí mật (sanitizer)
+
+Ngăn agent rò rỉ thông tin xác thực vào bối cảnh hoặc đầu ra của chúng. Các chính sách sanitizer kích hoạt trên các sự kiện **PostToolUse**. Khi Claude chạy lệnh Bash, đọc file hoặc gọi bất kỳ công cụ nào, các chính sách này kiểm tra đầu ra trước khi nó được trả lại cho Claude. Nếu phát hiện mẫu bí mật, chính sách trả lại quyết định từ chối ngăn chặn đầu ra được truyền lại.
+
+### `sanitize-jwt`
+
+**Sự kiện:** PostToolUse (tất cả công cụ)  
+**Mặc định:** Redacts các token JWT (ba đoạn base64url được phân tách bằng `.`).
+
+Không có tham số.
+
+---
+
+### `sanitize-api-keys`
+
+**Sự kiện:** PostToolUse (tất cả công cụ)  
+**Mặc định:** Redacts các định dạng khóa API phổ biến: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), khóa truy cập AWS (`AKIA`), khóa Stripe (`sk_live_`, `sk_test_`), và khóa API Google (`AIza`).
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Các mẫu regex bổ sung để coi là bí mật. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
+        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### `sanitize-connection-strings`
+
+**Sự kiện:** PostToolUse (tất cả công cụ)  
+**Mặc định:** Redacts chuỗi kết nối cơ sở dữ liệu chứa thông tin xác thực nhúng (ví dụ: `postgresql://user:password@host/db`).
+
+Không có tham số.
+
+---
+
+### `sanitize-private-key-content`
+
+**Sự kiện:** PostToolUse (tất cả công cụ)  
+**Mặc định:** Redacts các khối PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, v.v.).
+
+Không có tham số.
+
+---
+
+### `sanitize-bearer-tokens`
+
+**Sự kiện:** PostToolUse (tất cả công cụ)  
+**Mặc định:** Redacts các header `Authorization: Bearer <token>` trong đó token là 20 hoặc nhiều ký tự.
+
+Không có tham số.
+
+---
+
+## Môi trường
+
+Bảo vệ cấu hình môi trường nhạy cảm khỏi bị agent đọc hoặc làm lộ.
+
+### `block-env-files`
+
+**Sự kiện:** PreToolUse (Bash, Read)  
+**Mặc định:** Từ chối đọc file `.env` thông qua `cat .env`, gọi công cụ Read với `.env` làm đường dẫn file, v.v.
+
+Không chặn `.envrc` hoặc các file liên quan môi trường khác - chỉ các file tên chính xác là `.env`.
+
+Không có tham số.
+
+---
+
+### `protect-env-vars`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối các lệnh in ra các biến môi trường: `printenv`, `env`, `echo $VAR`.
+
+Không có tham số.
+
+---
+
+## Truy cập file
+
+Giữ agent làm việc trong ranh giới dự án và tránh xa file nhạy cảm.
+
+### `block-read-outside-cwd`
+
+**Sự kiện:** PreToolUse (Read, Bash)  
+**Mặc định:** Từ chối đọc file ngoài thư mục gốc dự án. Ranh giới là `CLAUDE_PROJECT_DIR` (được đặt một lần mỗi phiên bởi Claude Code), với fallback thành thư mục làm việc hiện tại của phiên khi biến đó không được đặt. Sử dụng thư mục gốc dự án thay vì `cwd` trực tiếp có nghĩa là ranh giới vẫn ổn định ngay cả sau khi Claude `cd` vào một thư mục con.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | Tiền tố đường dẫn tuyệt đối được phép ngay cả khi ngoài thư mục gốc dự án. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company/config"]
+    }
+  }
+}
+```
+
+---
+
+### `block-secrets-write`
+
+**Sự kiện:** PreToolUse (Write, Edit)  
+**Mặc định:** Từ chối ghi vào file thường được dùng cho khóa riêng tư và chứng chỉ: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `string[]` | `[]` | Các mẫu tên file bổ sung (kiểu glob) cần chặn. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-secrets-write": {
+      "additionalPatterns": [".token", ".secret"]
+    }
+  }
+}
+```
+
+---
+
+## Git
+
+Ngăn chặn đẩy ngẫu nhiên, force-push và lỗi nhánh khó hoàn tác.
+
+### `block-push-master`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối `git push origin main` và `git push origin master`.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | Tên nhánh không thể được đẩy trực tiếp. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "master", "release", "prod"]
+    }
+  }
+}
+```
+
+<Tip>
+Để cho phép đẩy đến tất cả các nhánh (tương đương với vô hiệu hóa chính sách này mà không loại bỏ khỏi `enabledPolicies`), đặt `protectedBranches: []`.
+</Tip>
+
+---
+
+### `block-work-on-main`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối `git commit`, `git merge`, `git rebase` và `git cherry-pick` khi cây làm việc ở trên `main` hoặc `master`. Tạo và chuyển nhánh (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) không bị ảnh hưởng.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | Tên nhánh mà commit/merge/rebase/cherry-pick bị từ chối. |
+
+---
+
+### `block-force-push`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Từ chối `git push --force` và `git push -f`.
+
+Không có tham số riêng của chính sách. Sử dụng [`hint`](/vi/configuration#hint-cross-cutting) cross-cutting để gợi ý thay thế:
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
+    }
+  }
+}
+```
+
+---
+
+### `warn-git-amend`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Hướng dẫn Claude cẩn thận khi chạy `git commit --amend`. Không chặn lệnh.
+
+Không có tham số.
+
+---
+
+### `warn-git-stash-drop`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy `git stash drop`. Không chặn lệnh.
+
+Không có tham số.
+
+---
+
+### `warn-all-files-staged`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Hướng dẫn Claude xem lại những gì nó đang tạo staging khi chạy `git add -A` hoặc `git add .`. Không chặn lệnh.
+
+Không có tham số.
+
+---
+
+## Cơ sở dữ liệu
+
+Bắt các hoạt động SQL tàn phá trước khi chúng thực thi chống lại cơ sở dữ liệu của bạn.
+
+### `warn-destructive-sql`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy SQL chứa `DROP TABLE`, `DROP DATABASE` hoặc `DELETE` không có mệnh đề `WHERE`.
+
+Không có tham số.
+
+---
+
+### `warn-schema-alteration`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy các câu lệnh `ALTER TABLE`.
+
+Không có tham số.
+
+---
+
+## Cảnh báo
+
+Cung cấp cho agent bối cảnh bổ sung trước các hoạt động có rủi ro tiềm ẩn nhưng không tàn phá.
+
+### `warn-large-file-write`
+
+**Sự kiện:** PreToolUse (Write)  
+**Mặc định:** Hướng dẫn Claude xác nhận trước khi ghi file lớn hơn 1024 KB.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `thresholdKb` | `number` | `1024` | Ngưỡng kích thước file tính bằng kilobyte trên đó cảnh báo được phát hành. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "warn-large-file-write": {
+      "thresholdKb": 256
+    }
+  }
+}
+```
+
+<Note>
+Trình xử lý hook thực thi giới hạn stdin 1 MB cho các tải trọng. Để kiểm tra chính sách này với nội dung nhỏ, đặt `thresholdKb` thành giá trị tốt dưới 1024.
+</Note>
+
+---
+
+### `warn-package-publish`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy `npm publish`.
+
+Không có tham số.
+
+---
+
+### `warn-background-process`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Hướng dẫn Claude cẩn thận khi khởi chạy các quy trình nền thông qua `nohup`, `&`, `disown` hoặc `screen`.
+
+Không có tham số.
+
+---
+
+### `warn-global-package-install`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy `npm install -g`, `yarn global add` hoặc `pip install` không có môi trường ảo.
+
+Không có tham số.
+
+---
+
+## Trình quản lý gói
+
+Thực thi trình quản lý gói nào mà agent được phép sử dụng.
+
+### `prefer-package-manager`
+
+**Sự kiện:** PreToolUse (Bash)  
+**Mặc định:** Vô hiệu hóa. Khi bật, chặn bất kỳ lệnh trình quản lý gói nào không có trong danh sách `allowed` và yêu cầu Claude viết lại lệnh bằng trình quản lý được phép.
+
+Phát hiện: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo.
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `allowed` | string[] | `[]` | Tên trình quản lý gói được phép. Bất kỳ trình quản lý nào được phát hiện không có trong danh sách này bị chặn. Khi trống, chính sách là no-op. |
+| `blocked` | string[] | `[]` | Tên trình quản lý bổ sung cần chặn ngoài danh sách tích hợp sẵn (ví dụ: `['pdm', 'pipx']`). |
+
+Danh sách chặn tích hợp sẵn bao gồm: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Sử dụng `blocked` để thêm trình quản lý không có trong danh sách này.
+
+**Ví dụ cấu hình:**
+
+```json
+{
+  "enabledPolicies": ["prefer-package-manager"],
+  "policyParams": {
+    "prefer-package-manager": {
+      "allowed": ["uv", "bun"],
+      "blocked": ["pdm", "pipx"]
+    }
+  }
+}
+```
+
+Với cấu hình này, cả `pip install flask` và `pdm install flask` đều bị từ chối với thông báo yêu cầu Claude sử dụng `uv` hoặc `bun`. Các lệnh như `uv pip install flask` được phép vì `uv` nằm trong danh sách cho phép và được kiểm tra trước.
+
+---
+
+## Hành vi AI
+
+Phát hiện khi agent bị mắc kẹt hoặc cư xử bất ngờ.
+
+### `warn-repeated-tool-calls`
+
+**Sự kiện:** PreToolUse (tất cả công cụ)  
+**Mặc định:** Hướng dẫn Claude xem xét lại khi cùng một công cụ được gọi 3+ lần với cùng các tham số - dấu hiệu phổ biến của agent bị mắc kẹt trong vòng lặp.
+
+Không có tham số.
+
+---
+
+## Quy trình làm việc
+
+Thực thi quy trình làm việc cuối phiên có kỷ luật. Các chính sách này kích hoạt trên sự kiện **Stop** và từ chối agent dừng lại cho đến khi mỗi điều kiện được đáp ứng. Chúng theo chuỗi phụ thuộc tự nhiên: commit → push → PR → CI. Nếu chính sách từ chối, các chính sách sau trong chuỗi bị bỏ qua (từ chối ngắn mạch).
+
+Tất cả các chính sách quy trình làm việc **fail-open**: nếu công cụ yêu cầu không khả dụng (ví dụ: `gh` không được cài đặt, không có git remote), chính sách cho phép với thông báo thông tin giải thích tại sao kiểm tra bị bỏ qua.
+
+### Ngữ nghĩa Stop trên mỗi CLI
+
+Thực thi Stop trông hơi khác nhau trên sáu CLI được hỗ trợ vì mỗi CLI đều hiển thị hợp đồng hook "agent hoàn thành" khác. **Kết quả** là như nhau — agent không thoát khỏi việc dừng lại khi cổng quy trình làm việc thất bại — nhưng **cơ chế** khác. Bảng dưới đây tóm tắt; chỉ Pi có một đặc điểm kỳ lạ được nhìn thấy bởi người dùng đáng hiểu trước khi bạn bật một chính sách `require-*-before-stop`.
+
+| CLI | Khi cổng kích hoạt | Bạn thấy gì |
+|---|---|---|
+| Claude Code | Cùng vòng lặp agent, ngay lập tức | Claude tiếp tục làm việc — sửa chữa vấn đề, sau đó cố gắng hoàn thành lại. Không có sự gián đoạn nào được nhìn thấy từ phía bạn. |
+| Codex | Cùng vòng lặp agent, ngay lập tức | Giống như Claude. |
+| GitHub Copilot CLI | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh `{decision:"block", reason}` của Copilot — được xác minh theo thực nghiệm chống lại Copilot CLI 1.0.41). |
+| Cursor Agent | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh `{followup_message}` của Cursor — được giới hạn ở `loop_limit`, mặc định 5 lần thử lại). |
+| OpenCode | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng SDK gọi `client.session.prompt(...)` được định tuyến qua `hookSpecificOutput.additionalContext`). |
+| **Pi (pi-coding-agent)** | **Lượt người dùng tiếp theo** | **Pi dừng lại rõ ràng** khi cổng kích hoạt — vòng lặp agent của nó thoát và bạn được trả về lời nhắc. Cổng kích hoạt vào lần tiếp theo bạn gửi lời nhắc: failproofai thêm vào trước một chỉ thị `MANDATORY ACTION REQUIRED` vào hệ thống prompt của lượt đó, hướng dẫn LLM hoàn thành bước quy trình làm việc (commit, push, v.v.) trước khi làm những gì bạn yêu cầu. |
+
+<Note>
+**Hạn chế Pi.** `AgentEndEvent` của Pi (tương đương hạ nguồn của Claude `Stop` hook) không có loại Result — khi nó kích hoạt, vòng lặp agent của Pi đã thoát. Pi không thể bị buộc phải thử lại cùng vòng lặp theo cách Claude / Copilot / Cursor / OpenCode có thể. failproofai dịch chuyển cổng đến sự kiện `before_agent_start` của Pi (kích hoạt sau lời nhắc người dùng tiếp theo) để kiểm tra quy trình làm việc vẫn thực thi, chỉ trên lượt tiếp theo thay vì lượt hiện tại.
+
+**Điều này có nghĩa gì trong thực tế:**
+
+- Sau khi Pi dừng lại, lý do từ chối được nắm bắt trong bộ nhớ được khóa theo id phiên Pi. Lời nhắc rất tiếp theo bạn gửi trong cùng một quy trình Pi thoát nó: LLM thấy chỉ thị `MANDATORY ACTION REQUIRED` ở đầu hệ thống prompt của nó, commits (hoặc pushes / mở PR / chờ CI), và chỉ sau đó tiếp tục với yêu cầu của bạn. Lý do từ chối được nắm bắt là một lần — một khi thoát, cổng rõ ràng.
+- Cổng được giới hạn bởi vòng đời quá trình Pi. Nếu bạn `Ctrl+C` Pi hoặc thoát giữa các lượt, mục trong bộ nhớ bị loại bỏ cùng với quá trình và cổng bị bỏ qua. Claude, Copilot, Cursor và OpenCode có giới hạn tương tự (giết agent và cổng bị bỏ qua) — Pi chỉ khiến nó rõ ràng hơn vì agent rõ ràng thoát trước khi cổng kích hoạt.
+- Một từ chối đang chờ xử lý cũng bị xóa trên `session_shutdown` vì bất kỳ lý do nào (`new` / `resume` / `fork` / `quit`), do đó một cổng cũ từ phiên trước không thể rò rỉ vào phiên mới được bắt đầu trong cùng quá trình Pi.
+
+Nếu bạn cần retry cùng vòng lặp kiểu Claude, chạy các chính sách `Stop` của bạn dưới bất kỳ năm CLI được hỗ trợ nào khác. Chúng tôi đang theo dõi Pi hạ nguồn để loại Result trong tương lai trên `AgentEndEvent` sẽ cho phép chúng tôi đóng khoảng trống này.
+</Note>
+
+### `require-commit-before-stop`
+
+**Sự kiện:** Stop  
+**Mặc định:** Từ chối dừng lại khi có các thay đổi chưa được commit (file được sửa, staged hoặc untracked). Trả lại thông báo thông tin khi thư mục làm việc sạch sẽ.
+
+Không có tham số.
+
+---
+
+### `require-push-before-stop`
+
+**Sự kiện:** Stop  
+**Mặc định:** Từ chối dừng lại khi có các commit chưa được đẩy hoặc khi nhánh hiện tại không có nhánh theo dõi từ xa. Gợi ý `git push -u` để tạo nhánh theo dõi nếu cần. Fails open nếu không có remote được cấu hình.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `remote` | `string` | `"origin"` | Tên remote để đẩy đến. |
+
+**Ví dụ:**
+
+```json
+{
+  "policyParams": {
+    "require-push-before-stop": {
+      "remote": "upstream"
+    }
+  }
+}
+```
+
+---
+
+### `require-pr-before-stop`
+
+**Sự kiện:** Stop  
+**Mặc định:** Từ chối dừng lại khi không có pull request cho nhánh hiện tại, hoặc khi PR hiện có bị đóng mà không merge. Hướng dẫn Claude tạo PR với `gh pr create`. Khi PR được **merge**, chính sách cho phép (công việc đã ship) và thông báo gợi ý chuyển đổi nhánh (`git checkout main && git pull`).
+
+Không có tham số.
+
+<Note>
+Chính sách này yêu cầu [GitHub CLI](https://cli.github.com/) (`gh`) được cài đặt và xác thực.
+Chạy `gh auth login` với mã thông báo truy cập cá nhân có phạm vi `repo` để truy cập đọc
+pull requests. Nếu `gh` không được cài đặt hoặc chưa được xác thực, chính sách fails open và báo cáo lý do cho Claude.
+</Note>
+
+---
+
+### `require-no-conflicts-before-stop`
+
+**Sự kiện:** Stop  
+**Mặc định:** Từ chối dừng lại khi nhánh hiện tại không thể merge sạch vào nhánh cơ sở. Chính sách trước tiên xác nhận có `OPEN` PR trên GitHub cho nhánh — nếu không có, không có mục tiêu merge để thực thi, do đó toàn bộ chính sách ngắn mạch để cho phép. Một khi xác nhận `OPEN` PR, hai bộ dò độc lập chạy:
+
+1. **Cục bộ** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. Xung đột, thông báo từ chối đặt tên các file xung đột để Claude biết chính xác những gì cần giải quyết.
+2. **GitHub** — tái sử dụng kết quả `gh pr view --json mergeable,state` đã được lấy trong kiểm tra trước. Bắt xung đột mà `origin/<baseBranch>` cũ cuc bộ sẽ bỏ lỡ (ví dụ: ai đó đã công bố PR xung đột trên `main` kể từ lần fetch cuối cùng). Kết quả `CONFLICTING` từ chối. Kết quả `UNKNOWN` cũng từ chối và hướng dẫn Claude chờ ~10 giây và kiểm tra lại trước khi cố gắng dừng lại — điều này ngăn chặn sai âm dương trong khi GitHub tính toán lại.
+
+Bỏ qua hoàn toàn (cho phép) khi: `gh` không được cài đặt, không có PR cho nhánh, trạng thái PR không phải `OPEN` (ví dụ: `MERGED`, `CLOSED`), hoặc `gh pr view` trả lại đầu ra không thể phân tích cú pháp. Cũng fails open khi `origin/<baseBranch>` bị thiếu cục bộ hoặc khi không có commit nào phía trước cơ sở — các sự rơi qua Tầng 1 đó vẫn tham khảo mergeability PR được lưu trong bộ nhớ đệm trước khi cho phép.
+
+**Tham số:**
+
+| Tham số | Loại | Mặc định | Mô tả |
+|-------|------|---------|-------------|
+| `baseBranch` | `string` | `"main"` | Nhánh cơ sở để kiểm tra xung đột chống lại. |
+
+<Note>
+GitHub CLI (`gh`) là bắt buộc đối với chính sách này. Chính sách sử dụng `gh pr view` để xác nhận
+có `OPEN` PR tồn tại trước khi chạy bất kỳ bộ dò xung đột — nếu không có `gh`, chính sách
+ngắn mạch để cho phép. Chạy `gh auth login` với mã thông báo truy cập cá nhân có phạm vi
+`repo` để truy cập đọc pull requests.
+</Note>
+
+---
+
+### `require-ci-green-before-stop`
+
+**Sự kiện:** Stop  
+**Mặc định:** Từ chối dừng lại khi kiểm tra CI đang thất bại hoặc vẫn đang chạy trên nhánh hiện tại. Kiểm tra cả GitHub Actions workflow chạy và kiểm tra bot của bên thứ ba (ví dụ: CodeRabbit, SonarCloud, Codecov). Coi `skipped`, `cancelled` và `neutral` là kết luận không thất bại (cái sau bao gồm ví dụ: cảnh báo Socket Security trên PR của người đóng góp bên ngoài, nơi ứng dụng có ý định báo cáo neutral thay vì thành công/thất bại). Trả lại thông báo thông tin khi tất cả kiểm tra vượt qua.
+
+Không có tham số.
+
+<Note>
+Chính sách này yêu cầu [GitHub CLI](https://cli.github.com/) (`gh`) được cài đặt và xác thực.
+Chạy `gh auth login` với mã thông báo truy cập cá nhân có phạm vi `repo` để truy cập đọc
+workflow chạy Actions và Checks API. Nếu `gh` không được cài đặt hoặc chưa được xác thực, chính sách fails open và báo cáo lý do cho Claude.
+</Note>
+
+---
+
+---
+
+## Vô hiệu hóa các chính sách riêng lẻ
+
+Loại bỏ một chính sách cụ thể khỏi `enabledPolicies` trong cấu hình của bạn, hoặc chuyển đổi nó tắt trong tab Chính sách của bảng điều khiển.
+
+```json
+{
+  "enabledPolicies": [
+    "block-rm-rf",
+    "sanitize-api-keys"
+  ]
+}
+```
+
+Các chính sách không được liệt kê trong `enabledPolicies` không chạy, ngay cả khi có mục `policyParams` tồn tại cho chúng.