> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Các chính sách tích hợp sẵn

> Tất cả 39 chính sách tích hợp sẵn bắt được các chế độ lỗi thông thường của agent

failproofai được trang bị 39 chính sách tích hợp sẵn bắt được các chế độ lỗi thông thường của agent. Mỗi chính sách được 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 tinh chỉnh hành vi của chúng mà không cần viết mã. Năm chính sách quy trình làm việc thực thi đường dẫ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 vào các danh mục:

| Danh mục                                   | Chính sách                                                                                                                                   | Loại hook   |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| [Lệnh nguy hiểm](#dangerous-commands)      | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands                                                                      | PreToolUse  |
| [Lệnh cơ sở hạ tầng](#infra-commands)      | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline                                     | PreToolUse  |
| [Bí mật (sanitizers)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens                           | PostToolUse |
| [Môi trường](#environment)                 | block-env-files, protect-env-vars                                                                                                            | PreToolUse  |
| [Truy cập tệp](#file-access)               | 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](#database)                 | warn-destructive-sql, warn-schema-alteration                                                                                                 | PreToolUse  |
| [Cảnh báo](#warnings)                      | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install                                            | PreToolUse  |
| [Trình quản lý gói](#package-managers)     | prefer-package-manager                                                                                                                       | PreToolUse  |
| [Quy trình làm việc](#workflow)            | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop        |

* **`block-`** — dừng agent không được tiếp tục.
* **`warn-`** — cung cấp ngữ cảnh bổ sung để agent có thể tự sửa chữa.
* **`sanitize-`** — loại bỏ dữ liệu nhạy cảm từ kết quả công cụ trước khi agent nhìn thấy.

### Không gian tên

Mỗi chính sách sống trong một vị trí `<namespace>/<name>`. Các chính sách tích hợp sẵn thuộc về
không gian tên **`failproofai/`** — ví dụ: `failproofai/sanitize-jwt`. Không gian tên
ngăn chặn va chạm 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 sẵn bằng tên ngắn hoặc tên
đủ điều kiện; cả hai dạng đều giải quyết thành cùng một chính sách:

```json theme={null}
{
  "enabledPolicies": [
    "sanitize-jwt",
    "failproofai/block-rm-rf"
  ]
}
```

Nếu một tên không có `/`, failproofai coi nó thuộc về không gian tên mặc định
`failproofai`. Các 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`. Hint được nối vào tin nhắn deny hoặc instruct mà Claude nhìn thấy, cung cấp hướng dẫn có thể hành động mà không sửa đổi mã 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à theo quy ước. Xem [Configuration → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết.
</Tip>

***

## Lệnh nguy hiểm

Ngăn chặn agent chạy các thao tác khó hoàn tác hoặc có thể làm hỏng hệ thống chủ nhà.

### `block-sudo`

**Sự kiện:** PreToolUse (Bash)\
**Mặc định:** Từ chối bất kỳ lệnh `sudo` nào.

Chặn các lần gọi bao gồm từ khóa `sudo`. Phối hợp mẫu được thực hiện trên các token lệnh được phân tích cú pháp, không phải chuỗi thô, để ngăn chặn bypass qua tiêm toán tử shell.

**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 khớp với các token argv được phân tích cú pháp. |

**Ví dụ:**

```json theme={null}
{
  "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 khớp 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 qua các toán tử shell được thêm vào (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[]` | `[]`     | Đường dẫn an toàn để xóa đệ quy (ví dụ: `/tmp`). |

**Ví dụ:**

```json theme={null}
{
  "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ố.

***

## Lệnh cơ sở hạ tầng

Dừng các 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 hợp pháp cần 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 được bật, mỗi lần gọi CLI phù hợ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 khớp 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 toán tử shell độc lập (`&&`, `||`, `|`, `;`) hoặc token có ký tự siêu dữ liệu shell nhúng bị từ chối trước khi so 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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 phụ CLI `gh` sau đây gây ra 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 phụ `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 các kiểm tra quy trình làm việc (bao gồm cả chính sách `require-ci-green-before-stop` của failproofai).

**Tham số:**

| Tham số         | Loại       | Mặc định | Mô tả                                                                               |
| --------------- | ---------- | -------- | ----------------------------------------------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`     | Các lệnh gọi được viết kịch bản cụ thể để cho phép ngay cả khi chúng sẽ bị từ chối. |

**Ví dụ:**

```json theme={null}
{
  "policyParams": {
    "block-gh-pipeline": {
      "allowPatterns": ["gh run rerun *"]
    }
  }
}
```

***

## Bí mật (sanitizers)

Dừng agent rò rỉ thông tin đăng nhập vào ngữ cảnh hoặc kết quả của chúng. Các chính sách sanitizer được kích hoạt trên các sự kiện **PostToolUse**. Khi Claude chạy lệnh Bash, đọc tệp hoặc gọi bất kỳ công cụ nào, các chính sách này kiểm tra kết quả trước khi nó được trả về Claude. Nếu phát hiện mẫu bí mật, chính sách trả về quyết định deny ngăn chặn kết quả được truyền lại.

### `sanitize-jwt`

**Sự kiện:** PostToolUse (tất cả công cụ)\
**Mặc định:** Che khuất các token JWT (ba đoạn base64url được phân cách bằng `.`).

Không có tham số.

***

### `sanitize-api-keys`

**Sự kiện:** PostToolUse (tất cả công cụ)\
**Mặc định:** Che khuất các định dạng khóa API phổ biến: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS access keys (`AKIA`), Stripe keys (`sk_live_`, `sk_test_`) và Google API keys (`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 theme={null}
{
  "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:** Che khuất chuỗi kết nối cơ sở dữ liệu chứa thông tin đăng nhập 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:** Che khuất 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:** Che khuất các tiêu đề `Authorization: Bearer <token>` nơi token là 20 hoặc nhiều ký tự hơn.

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 việc agent đọc hoặc tiếp xúc.

### `block-env-files`

**Sự kiện:** PreToolUse (Bash, Read)\
**Mặc định:** Từ chối đọc tệp `.env` qua `cat .env`, gọi công cụ `Read` với `.env` là đường dẫn tệp, v.v.

Không chặn `.envrc` hoặc các tệp liên quan môi trường khác - chỉ những tệp được đặt 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 biến môi trường: `printenv`, `env`, `echo $VAR`.

Không có tham số.

***

## Truy cập tệp

Giữ agent làm việc trong ranh giới dự án và tránh xa những tệp nhạy cảm.

### `block-read-outside-cwd`

**Sự kiện:** PreToolUse (Read, Bash)\
**Mặc định:** Từ chối đọc tệp bên ngoài 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 dự phòng là thư mục làm việc hiện tại của phiên khi biến đó chưa được đặt. Sử dụng 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 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 bên ngoài gốc dự án. |

**Ví dụ:**

```json theme={null}
{
  "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 các tệp thường được sử dụng cho các 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 tệp bổ sung (kiểu glob) để chặn. |

**Ví dụ:**

```json theme={null}
{
  "policyParams": {
    "block-secrets-write": {
      "additionalPatterns": [".token", ".secret"]
    }
  }
}
```

***

## Git

Ngăn chặn các lần push tình cờ, force-push và các 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 push trực tiếp. |

**Ví dụ:**

```json theme={null}
{
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "master", "release", "prod"]
    }
  }
}
```

<Tip>
  Để cho phép push đến tất cả các nhánh (có hiệu lực là vô hiệu hóa chính sách này mà không xóa nó 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 nằm trên `main` hoặc `master`. Tạo nhánh và chuyển đổi (`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 trong đó 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ố cụ thể chính sách. Sử dụng [`hint`](/vi/configuration#hint-cross-cutting) cắt ngang để gợi ý các giải pháp thay thế:

```json theme={null}
{
  "policyParams": {
    "block-force-push": {
      "hint": "Tạo một nhánh mới từ HEAD hiện tại của bạn (ví dụ: `git checkout -b <new-branch>`) và push nhánh đó thay vì."
    }
  }
}
```

***

### `warn-git-amend`

**Sự kiện:** PreToolUse (Bash)\
**Mặc định:** Hướng dẫn Claude tiến hành 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ó sắp sàng lọc 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 thao tác SQL phá hủy trước khi chúng thực thi đối vớ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` mà 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 agent ngữ cảnh bổ sung trước các hoạt động tiềm ẩn rủi ro nhưng không phá hủy.

### `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 các tệp 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 tệp tính bằng kilobyte mà cảnh báo được phát hành. |

**Ví dụ:**

```json theme={null}
{
  "policyParams": {
    "warn-large-file-write": {
      "thresholdKb": 256
    }
  }
}
```

<Note>
  Xử lý hook thực thi giới hạn stdin 1 MB trên 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 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` mà 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 agent được phép sử dụng.

### `prefer-package-manager`

**Sự kiện:** PreToolUse (Bash)\
**Mặc định:** Bị vô hiệu hóa. Khi được bật, chặn bất kỳ lệnh trình quản lý gói nào không 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\[] | `[]`     | Các tên trình quản lý gói được phép. Bất kỳ trình quản lý được phát hiện nào không có trong danh sách này bị chặn. Khi trống, chính sách là no-op. |
| `blocked` | string\[] | `[]`     | Các tên trình quản lý bổ sung để 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 các trình quản lý không có trong danh sách này.

**Cấu hình ví dụ:**

```json theme={null}
{
  "enabledPolicies": ["prefer-package-manager"],
  "policyParams": {
    "prefer-package-manager": {
      "allowed": ["uv", "bun"],
      "blocked": ["pdm", "pipx"]
    }
  }
}
```

Với cấu hình này, `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` thay vì. 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 tiên.

***

## Hành vi AI

Phát hiện khi agent bị mắc kẹt hoặc có hành vi bất thườ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 trở lên với các tham số giống hệt nhau - dấu hiệu phổ biến của agent bị mắc 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 kỷ luật. Các chính sách này được 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 tuân 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 (deny short-circuits).

Tất cả các chính sách quy trình làm việc là **fail-open**: nếu công cụ được yêu cầu không có sẵn (ví dụ: `gh` không 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 lý do kiểm tra bị bỏ qua.

### Ngữ nghĩa Stop theo CLI

Thực thi Stop trông hơi khác nhau trên bảy CLI được hỗ trợ vì mỗi CLI tiếp xúc với hợp đồng hook "agent kết thúc" khác nhau. **Kết quả** là như nhau — agent không thoát khỏi việc dừng lại trong khi cổng quy trình làm việc đang thất bại — nhưng **cơ chế** khác nhau. Bảng dưới đây tóm tắt; chỉ Pi có một điểm kỳ lạ hiển thị cho người dùng đáng hiểu trước khi bạn bật chính sách `require-*-before-stop`.

| CLI                      | Khi cổng kích hoạt                | Những gì bạn thấy                                                                                                                                                                                                                                                                                                                                               |
| ------------------------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 vấn đề, sau đó cố gắng hoàn thành lại. Không có sự gián đoạn hiển thị cho 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}` retry của Copilot — đã xác minh theo kinh nghiệm đối vớ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 — bị 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 lệnh gọi SDK `client.session.prompt(...)` của OpenCode được định tuyến qua `hookSpecificOutput.additionalContext`).                                                                                                                                                                                                                   |
| **Pi (pi-coding-agent)** | **Lần tới người dùng**            | **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 quay lại dấu nhắc. Cổng sau đó kích hoạt lần tiếp theo bạn gửi dấu nhắc: failproofai thêm tiền tố `MANDATORY ACTION REQUIRED` vào lời nhắc hệ thống của lần đó, 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 bất cứ điều gì bạn yêu cầu. |

<Note>
  **Giới hạn Pi.** `AgentEndEvent` của Pi (tương đương thượng nguồn của hook `Stop` của Claude) 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 thử lại cùng một vòng lặp theo cách Claude / Copilot / Cursor / OpenCode. failproofai thay đổi cổng sang sự kiện `before_agent_start` của Pi (được kích hoạt sau dấu 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ần tới thay vì lần 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 ghi vào bộ nhớ trong bằng id phiên Pi. Dấu nhắc rất tiếp theo bạn gửi trong cùng quy trình Pi lấy ra nó: LLM nhìn thấy chỉ thị `MANDATORY ACTION REQUIRED` ở đầu lời nhắc hệ thống của nó, commit (hoặc push / mở PR / chờ CI) và chỉ khi đó tiếp tục với yêu cầu của bạn. Lý do từ chối được ghi lại là một lần — sau khi lấy ra, cổng rõ ràng.
  * Cổng bị ràng buộc 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ần, mục bộ nhớ trong được loại bỏ cùng với quá trình và cổng bị bỏ lỡ. Claude, Copilot, Cursor và OpenCode có cùng ranh giới (giết agent và cổng bị bỏ lỡ) — Pi chỉ làm cho 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ờ cũng bị xóa trên `session_shutdown` vì lý do gì đó (`new` / `resume` / `fork` / `quit`), vì vậy cổng cũ từ phiên trước không thể bị rò rỉ vào phiên mới được khởi động trong cùng quy trình Pi.

  Nếu bạn cần thử lại cùng vòng lặp kiểu Claude, hãy chạy các chính sách `Stop` của bạn dưới bất kỳ năm CLI được hỗ trợ khác. Chúng tôi đang theo dõi Pi thượng nguồn để có loại Result trong tương lai trên `AgentEndEvent` sẽ cho phép chúng tôi đóng khoảng cách này.
</Note>

### `require-commit-before-stop`

**Sự kiện:** Stop\
**Mặc định:** Từ chối dừng lại khi có thay đổi chưa được xác nhận (tệp đã sửa đổi, được sắp xếp hoặc chưa theo dõi). Trả về 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 lần commit chưa được push 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. Thất bại mở 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 để push đến. |

**Ví dụ:**

```json theme={null}
{
  "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ó yêu cầu pull tồn tại 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 đã được gửi) và thông báo gợi ý chuyển ra khỏ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 token truy cập cá nhân có phạm vi `repo` để đọc
  yêu cầu pull. Nếu `gh` không được cài đặt hoặc không xác thực, chính sách thất bại mở 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ó PR `OPEN` trên GitHub cho nhánh — nếu không có, không có mục tiêu merge để thực thi, vì vậy toàn bộ chính sách short-circuit cho phép. Khi PR `OPEN` được xác nhận, hai điều tra độc lập chạy:

1. **Local** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. Xung đột, thông báo từ chối đặt tên các tệp xung đột để Claude biết chính xác phải giải quyết cái gì.
2. **GitHub** — tái sử dụng kết quả `gh pr view --json mergeable,state` đã được tìm nạp trong kiểm tra trước. Bắt những xung đột mà `origin/<baseBranch>` cũ cục bộ sẽ bỏ lỡ (ví dụ: ai đó đã hạ cánh PR xung đột trên `main` kể từ lần tìm nạp 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 lại — điều này ngăn chặn dương tính giả 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 nào cho nhánh, trạng thái PR không phải `OPEN` (ví dụ: `MERGED`, `CLOSED`), hoặc `gh pr view` trả về kết quả không thể phân tích. Cũng thất bại mở khi `origin/<baseBranch>` bị thiếu cục bộ hoặc khi không có commit trước cơ sở — những lần rơi qua Layer 1 đó vẫn tham khảo kết quả PR mergeability được lưu trong bộ nhớ cache 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 đối với. |

<Note>
  GitHub CLI (`gh`) là bắt buộc cho chính sách này. Chính sách sử dụng `gh pr view` để xác nhận
  một PR `OPEN` tồn tại trước khi chạy bất kỳ điều tra xung đột nào — nếu không có `gh`, chính sách
  short-circuit cho phép. Chạy `gh auth login` với token truy cập cá nhân có
  phạm vi `repo` để đọc yêu cầu pull.
</Note>

***

### `require-ci-green-before-stop`

**Sự kiện:** Stop\
**Mặc định:** Từ chối dừng lại khi các kiểm tra CI đang thất bại hoặc vẫn chạy trên nhánh hiện tại. Kiểm tra cả công việc GitHub Actions workflow và các kiểm tra bot của bên thứ ba (ví dụ: CodeRabbit, SonarCloud, Codecov). Coi `skipped`, `cancelled` và `neutral` kết luận là không thất bại (cái sau bao gồm ví dụ: Socket Security alerts trên PR của người đóng góp bên ngoài, nơi ứng dụng cố tình báo cáo neutral thay vì success/failure). Trả về thông báo thông tin khi tất cả cá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 token truy cập cá nhân có phạm vi `repo` để đọc
  quy trình làm việc Actions và Checks API. Nếu `gh` không được cài đặt hoặc không xác thực, chính sách thất bại mở và báo cáo lý do cho Claude.
</Note>

***

***

## Vô hiệu hóa các chính sách riêng lẻ

Xóa một chính sách cụ thể khỏi `enabledPolicies` trong cấu hình của bạn hoặc bật tắt nó trên tab Policies của bảng điều khiển.

```json theme={null}
{
  "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ác mục `policyParams` tồn tại cho chúng.