failproofai 0.0.2 → 0.0.4-beta.0

package/.next/standalone/docs/vi/cli/list-policies.mdx

@@ -0,0 +1,31 @@
+---
+title: Liệt kê các chính sách
+description: "Xem các chính sách đã bật, tham số của chúng và chính sách tùy chỉnh"
+---
+
+```bash
+failproofai policies
+```
+
+Hiển thị tất cả các chính sách với trạng thái, tham số được cấu hình và chính sách tùy chỉnh.
+
+## Kết quả mẫu
+
+```text
+Failproof AI Hook Policies (user)
+
+  Status  Name                          Description
+  ──────  ──────────────────────────────────────────────────────────────
+  ✓       block-sudo                    Block sudo commands
+            allowPatterns: ["sudo systemctl status"]
+  ✓       block-rm-rf                   Block recursive deletions
+  ✗       block-curl-pipe-sh            Block curl|bash patterns
+  ✓       sanitize-api-keys             Redact API keys from output
+            additionalPatterns: [{ regex: "MY_TOKEN_...", label: "..." }]
+
+  ── Custom Policies (/home/alice/myproject/my-policies.js) ──────────────
+  ✓       require-jira-ticket           Block commits without ticket
+  ✓       approval-gate                 Approval gate for destructive ops
+```
+
+Các khóa không xác định trong `policyParams` sẽ được đánh dấu tại đây để bạn có thể phát hiện lỗi đánh máy sớm.

package/.next/standalone/docs/vi/cli/remove-policies.mdx

@@ -0,0 +1,43 @@
+---
+title: Gỡ cài đặt policies
+description: "Xóa các hook entries từ settings của Claude Code"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+Xóa các failproofai hook entries từ `settings.json` của Claude Code.
+
+Bí danh: `failproofai p -u`
+
+## Options
+
+| Flag | Mô tả |
+|------|-------------|
+| `--scope user` | Xóa từ global settings (mặc định) |
+| `--scope project` | Xóa từ project settings |
+| `--scope local` | Xóa từ local settings |
+| `--scope all` | Xóa từ tất cả các scopes cùng lúc |
+| `--custom` / `-c` | Xóa `customPoliciesPath` khỏi config |
+
+## Hành vi
+
+- **Không có tên policy** - xóa tất cả failproofai hook entries khỏi file settings
+- **Tên cụ thể** - tắt các policies đó nhưng giữ lại hooks đã cài đặt
+
+## Ví dụ
+
+```bash
+# Remove all hooks globally
+failproofai policies --uninstall
+
+# Disable a specific policy (keeps hooks installed)
+failproofai policies --uninstall block-sudo
+
+# Remove hooks from every scope
+failproofai policies --uninstall --scope all
+
+# Clear custom policies path
+failproofai policies --uninstall --custom
+```

package/.next/standalone/docs/vi/cli/version.mdx

@@ -0,0 +1,13 @@
+---
+---
+title: Kiểm tra phiên bản
+description: "In ra phiên bản failproofai đã cài đặt"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+In ra số phiên bản đã cài đặt.

package/.next/standalone/docs/vi/configuration.mdx

@@ -0,0 +1,222 @@
+---
+title: Cấu hình
+description: "Định dạng tệp cấu hình, hệ thống ba phạm vi và quy tắc hợp nhất"
+icon: gear
+---
+
+failproofai sử dụng các tệp cấu hình JSON để kiểm soát các chính sách nào được kích hoạt, cách chúng hoạt động và nơi tải các chính sách tùy chỉnh. Cấu hình được thiết kế để dễ dàng chia sẻ với nhóm của bạn - cam kết nó vào repo của bạn và mỗi nhà phát triển sẽ nhận được cùng một lưới an toàn tác nhân.
+
+---
+
+## Phạm vi cấu hình
+
+Có ba phạm vi cấu hình, được đánh giá theo thứ tự ưu tiên:
+
+| Phạm vi | Đường dẫn tệp | Mục đích |
+|--------|--------------|---------|
+| **project** | `.failproofai/policies-config.json` | Cài đặt trên mỗi repo, được cam kết vào kiểm soát phiên bản |
+| **local** | `.failproofai/policies-config.local.json` | Ghi đè cá nhân trên mỗi repo, được gitignore |
+| **global** | `~/.failproofai/policies-config.json` | Giá trị mặc định ở cấp người dùng trên tất cả các dự án |
+
+Khi failproofai nhận một sự kiện hook, nó tải và hợp nhất cả ba tệp tồn tại cho thư mục làm việc hiện tại.
+
+### Quy tắc hợp nhất
+
+**`enabledPolicies`** - hợp của tất cả ba phạm vi. Một chính sách được kích hoạt ở bất kỳ mức nào sẽ hoạt động.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← loại bỏ trùng lặp
+```
+
+**`policyParams`** - phạm vi đầu tiên xác định các tham số cho một chính sách nào đó sẽ chiến thắng hoàn toàn. Không có hợp nhất sâu các giá trị trong tham số của một chính sách.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project chiến thắng, global bị bỏ qua
+```
+
+```text
+project:  (không có mục block-sudo)
+local:    (không có mục block-sudo)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← rơi xuống global
+```
+
+**`customPoliciesPath`** - phạm vi đầu tiên xác định nó sẽ chiến thắng.
+
+**`llm`** - phạm vi đầu tiên xác định nó sẽ chiến thắng.
+
+---
+
+## Định dạng tệp cấu hình
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "sanitize-jwt",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"]
+    },
+    "block-rm-rf": {
+      "allowPaths": ["/tmp"]
+    },
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company"]
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  },
+  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
+}
+```
+
+---
+
+## Tham chiếu trường
+
+### `enabledPolicies`
+
+Loại: `string[]`
+
+Danh sách tên chính sách cần bật. Tên phải khớp chính xác với các định danh chính sách được hiển thị bởi `failproofai policies`. Xem [Chính sách tích hợp](/vi/built-in-policies) để có danh sách đầy đủ.
+
+Các chính sách không nằm trong `enabledPolicies` không hoạt động, ngay cả khi chúng có mục trong `policyParams`.
+
+### `policyParams`
+
+Loại: `Record<string, Record<string, unknown>>`
+
+Ghi đè tham số cho mỗi chính sách. Khóa bên ngoài là tên chính sách; các khóa bên trong là khóa dành riêng cho chính sách. Mỗi chính sách ghi lại các tham số khả dụng của nó trong [Chính sách tích hợp](/vi/built-in-policies).
+
+Nếu một chính sách có các tham số nhưng bạn không chỉ định chúng, các giá trị mặc định tích hợp của chính sách sẽ được sử dụng. Người dùng không cấu hình `policyParams` sẽ nhận được hành vi giống hệt như các phiên bản trước đó.
+
+Các khóa không xác định bên trong khối tham số của một chính sách sẽ bị bỏ qua khi hook được kích hoạt nhưng được đánh dấu là cảnh báo khi bạn chạy `failproofai policies`.
+
+#### `hint` (cross-cutting)
+
+Loại: `string` (tùy chọn)
+
+Một thông điệp được thêm vào lý do khi một chính sách trả về `deny` hoặc `instruct`. Sử dụng nó để đưa ra hướng dẫn hành động cho Claude mà không cần sửa đổi chính sách.
+
+Hoạt động với bất kỳ loại chính sách nào — tích hợp, tùy chỉnh (`custom/`), quy ước dự án (`.failproofai-project/`), hoặc quy ước người dùng (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Try creating a fresh branch instead."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Use apt-get directly without sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Ask the user for approval first."
+    }
+  }
+}
+```
+
+Khi `block-force-push` từ chối, Claude sẽ thấy: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+
+Các giá trị không phải chuỗi và chuỗi rỗng sẽ bị bỏ qua. Nếu `hint` không được đặt, hành vi không thay đổi (tương thích ngược).
+
+### `customPoliciesPath`
+
+Loại: `string` (đường dẫn tuyệt đối)
+
+Đường dẫn đến tệp JavaScript chứa các chính sách hook tùy chỉnh. Điều này được đặt tự động bởi `failproofai policies --install --custom <path>` (đường dẫn được giải quyết thành tuyệt đối trước khi được lưu trữ).
+
+Tệp được tải mới trên mỗi sự kiện hook - không có lưu cache. Xem [Chính sách tùy chỉnh](/vi/custom-policies) để biết chi tiết tác giả.
+
+### Chính sách dựa trên quy ước (v0.0.2-beta.7+)
+
+Ngoài `customPoliciesPath` rõ ràng, failproofai tự động phát hiện và tải các tệp chính sách từ thư mục `.failproofai/policies/`:
+
+| Mức | Thư mục | Phạm vi |
+|-----|--------|--------|
+| Dự án | `.failproofai/policies/` | Chia sẻ với nhóm qua kiểm soát phiên bản |
+| Người dùng | `~/.failproofai/policies/` | Cá nhân, áp dụng cho tất cả các dự án |
+
+**Khớp tệp:** Chỉ các tệp khớp `*policies.{js,mjs,ts}` được tải (ví dụ: `security-policies.mjs`, `workflow-policies.js`). Các tệp khác trong thư mục sẽ bị bỏ qua.
+
+**Không cần cấu hình:** Chính sách quy ước không yêu cầu mục nhập trong `policies-config.json`. Chỉ cần thả các tệp vào thư mục và chúng sẽ được nhận trên sự kiện hook tiếp theo.
+
+**Tải kết hợp:** Cả thư mục quy ước dự án và người dùng đều được quét. Tất cả các tệp phù hợp từ cả hai mức được tải (không giống như `customPoliciesPath` sử dụng first-scope-wins).
+
+Xem [Chính sách tùy chỉnh](/vi/custom-policies) để biết thêm chi tiết và ví dụ.
+
+### `llm`
+
+Loại: `object` (tùy chọn)
+
+Cấu hình máy khách LLM cho các chính sách thực hiện các lệnh gọi AI. Không bắt buộc đối với hầu hết các thiết lập.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Quản lý cấu hình từ CLI
+
+Các lệnh `policies --install` và `policies --uninstall` ghi vào `settings.json` của Claude Code (các điểm vào hook), trong khi `policies-config.json` là tệp bạn quản lý trực tiếp. Hai cái này là riêng biệt:
+
+- **`settings.json`** - yêu cầu Claude Code gọi `failproofai --hook <event>` trên mỗi lần sử dụng công cụ
+- **`policies-config.json`** - yêu cầu failproofai đánh giá chính sách nào và với những tham số nào
+
+Bạn có thể chỉnh sửa `policies-config.json` trực tiếp bất kỳ lúc nào; các thay đổi có hiệu lực ngay trên sự kiện hook tiếp theo mà không cần khởi động lại.
+
+---
+
+## Ví dụ: cấu hình cấp dự án với giá trị mặc định nhóm
+
+Cam kết `.failproofai/policies-config.json` vào repo của bạn:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Mỗi nhà phát triển sau đó có thể tạo `.failproofai/policies-config.local.json` (được gitignore) cho các ghi đè cá nhân mà không ảnh hưởng đến đồng nghiệp.

package/.next/standalone/docs/vi/custom-policies.mdx

@@ -0,0 +1,357 @@
+---
+title: Chính sách Tùy chỉnh
+description: "Viết các quy tắc riêng của bạn bằng JavaScript - thực thi các quy ước, ngăn chặn sự trôi dạt, phát hiện các lỗi, tích hợp với các hệ thống bên ngoài"
+icon: code
+---
+
+Chính sách tùy chỉnh cho phép bạn viết các quy tắc cho bất kỳ hành động của agent nào: thực thi các quy ước dự án, ngăn chặn sự trôi dạt, chặn các hoạt động có tính hủy diệt, phát hiện các agent bị kẹt, hoặc tích hợp với Slack, quy trình phê duyệt, v.v. Chúng sử dụng cùng một hệ thống sự kiện hook và các quyết định `allow`, `deny`, `instruct` như các chính sách tích hợp.
+
+---
+
+## Ví dụ nhanh
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+Cài đặt nó:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Hai cách để tải chính sách tùy chỉnh
+
+### Lựa chọn 1: Dựa trên quy ước (được khuyến nghị, v0.0.2-beta.7+)
+
+Thả các tệp `*policies.{js,mjs,ts}` vào `.failproofai/policies/` và chúng sẽ được tải tự động — không cần cờ hoặc thay đổi cấu hình. Cách này hoạt động giống như git hooks: thả một tệp, nó sẽ hoạt động.
+
+```
+# Mức dự án — được cam kết với git, chia sẻ với đội
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Mức người dùng — cá nhân, áp dụng cho tất cả các dự án
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Cách hoạt động:**
+- Cả hai thư mục dự án và người dùng được quét (union — không phải first-scope-wins)
+- Các tệp được tải theo thứ tự bảng chữ cái trong mỗi thư mục. Thêm tiền tố `01-`, `02-` để kiểm soát thứ tự
+- Chỉ các tệp khớp với `*policies.{js,mjs,ts}` được tải; các tệp khác bị bỏ qua
+- Mỗi tệp được tải độc lập (fail-open cho mỗi tệp)
+- Hoạt động cùng với các chính sách `--custom` rõ ràng và tích hợp
+
+<Tip>
+Chính sách quy ước là cách dễ nhất để chia sẻ chính sách trên toàn đội. Cam kết `.failproofai/policies/` với git và mỗi thành viên đội sẽ tự động nhận được chúng.
+</Tip>
+
+### Lựa chọn 2: Đường dẫn tệp rõ ràng
+
+```bash
+# Cài đặt với tệp chính sách tùy chỉnh
+failproofai policies --install --custom ./my-policies.js
+
+# Thay thế đường dẫn tệp chính sách
+failproofai policies --install --custom ./new-policies.js
+
+# Xóa đường dẫn chính sách tùy chỉnh khỏi cấu hình
+failproofai policies --uninstall --custom
+```
+
+Đường dẫn tuyệt đối được phân giải được lưu trữ trong `policies-config.json` dưới dạng `customPoliciesPath`. Tệp được tải lại trên mỗi sự kiện hook - không có bộ nhớ cache giữa các sự kiện.
+
+### Sử dụng cả hai cùng nhau
+
+Chính sách quy ước và tệp `--custom` rõ ràng có thể cùng tồn tại. Thứ tự tải:
+
+1. Tệp `customPoliciesPath` rõ ràng (nếu được cấu hình)
+2. Tệp quy ước dự án (`{cwd}/.failproofai/policies/`, theo thứ tự bảng chữ cái)
+3. Tệp quy ước người dùng (`~/.failproofai/policies/`, theo thứ tự bảng chữ cái)
+
+---
+
+## API
+
+### Nhập
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Đăng ký một chính sách. Gọi hàm này bao nhiêu lần cần thiết cho nhiều chính sách trong cùng một tệp.
+
+```ts
+customPolicies.add({
+  name: string;                         // required - unique identifier
+  description?: string;                 // shown in `failproofai policies` output
+  match?: { events?: HookEventType[] }; // filter by event type; omit to match all
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Trợ giúp quyết định
+
+| Hàm | Tác động | Sử dụng khi |
+|-----|---------|-----------|
+| `allow()` | Cho phép hoạt động im lặng | Hành động an toàn, không cần tin nhắn |
+| `deny(message)` | Chặn hoạt động | Agent không nên thực hiện hành động này |
+| `instruct(message)` | Thêm bối cảnh mà không chặn | Cung cấp cho agent bối cảnh bổ sung để tiếp tục theo đúng hướng |
+
+`deny(message)` - thông báo sẽ xuất hiện cho Claude với tiền tố `"Blocked by failproofai:"`. Một `deny` duy nhất sẽ ngắt khoá tất cả các đánh giá tiếp theo.
+
+`instruct(message)` - thông báo được nối thêm vào bối cảnh của Claude cho lệnh gọi công cụ hiện tại. Tất cả các thông báo `instruct` được tích lũy và gửi cùng nhau.
+
+<Tip>
+Bạn có thể nối thêm hướng dẫn bổ sung vào bất kỳ thông báo `deny` hoặc `instruct` nào bằng cách thêm trường `hint` trong `policyParams` — không cần thay đổi mã. Điều này hoạt động cho các chính sách tùy chỉnh (`custom/`), quy ước dự án (`.failproofai-project/`), và quy ước người dùng (`.failproofai-user/`) cũng vậy. Xem [Cấu hình → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết.
+</Tip>
+
+### Thông báo allow thông tin (beta)
+
+<Note>
+`allow(message)` là tính năng beta có sẵn từ v0.0.2-beta.3. API có thể thay đổi trong các phiên bản tương lai. Các phiên bản trước chỉ hỗ trợ `allow()` mà không có đối số.
+</Note>
+
+`allow(message)` cho phép hoạt động **và** gửi một thông báo thông tin quay lại cho Claude. Thông báo được gửi dưới dạng `additionalContext` trong phản hồi stdout của trình xử lý hook — cơ chế tương tự được sử dụng bởi `instruct`, nhưng về mặt ngữ nghĩa khác: đó là một cập nhật trạng thái, không phải cảnh báo.
+
+| Hàm | Tác động | Sử dụng khi |
+|-----|---------|-----------|
+| `allow(message)` | Cho phép và gửi bối cảnh cho Claude | Xác nhận kiểm tra đã vượt qua, hoặc giải thích tại sao một kiểm tra bị bỏ qua |
+
+Các trường hợp sử dụng:
+- **Xác nhận trạng thái:** `allow("All CI checks passed.")` — cho Claude biết mọi thứ đang ổn
+- **Giải thích fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — cho Claude biết tại sao một kiểm tra bị bỏ qua để nó có đầy đủ bối cảnh
+- **Nhiều thông báo tích lũy:** nếu nhiều chính sách mỗi cái trả về `allow(message)`, tất cả các thông báo được nối lại bằng dòng mới và gửi cùng nhau
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### Các trường `PolicyContext`
+
+| Trường | Loại | Mô tả |
+|--------|------|-------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | Công cụ được gọi (ví dụ: `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Các tham số đầu vào của công cụ |
+| `payload` | `Record<string, unknown>` | Toàn bộ tải trọng sự kiện thô từ Claude Code |
+| `session` | `SessionMetadata \| undefined` | Bối cảnh phiên (xem bên dưới) |
+
+### Các trường `SessionMetadata`
+
+| Trường | Loại | Mô tả |
+|--------|------|-------|
+| `sessionId` | `string` | Mã định danh phiên Claude Code |
+| `cwd` | `string` | Thư mục làm việc của phiên Claude Code |
+| `transcriptPath` | `string` | Đường dẫn đến tệp transcript JSONL của phiên |
+
+### Các loại sự kiện
+
+| Sự kiện | Khi nó kích hoạt | Nội dung `toolInput` |
+|--------|-----------------|-----------------|
+| `PreToolUse` | Trước khi Claude chạy một công cụ | Đầu vào của công cụ (ví dụ: `{ command: "..." }` cho Bash) |
+| `PostToolUse` | Sau khi một công cụ hoàn thành | Đầu vào của công cụ + `tool_result` (đầu ra) |
+| `Notification` | Khi Claude gửi thông báo | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks phải luôn trả về `allow()`, chúng không thể chặn thông báo |
+| `Stop` | Khi phiên Claude kết thúc | Trống |
+
+---
+
+## Thứ tự đánh giá
+
+Chính sách được đánh giá theo thứ tự này:
+
+1. Chính sách tích hợp (theo thứ tự định nghĩa)
+2. Chính sách tùy chỉnh rõ ràng từ `customPoliciesPath` (theo thứ tự `.add()`)
+3. Chính sách quy ước từ dự án `.failproofai/policies/` (tệp theo thứ tự bảng chữ cái, `.add()` theo thứ tự trong)
+4. Chính sách quy ước từ người dùng `~/.failproofai/policies/` (tệp theo thứ tự bảng chữ cái, `.add()` theo thứ tự trong)
+
+<Note>
+`deny` đầu tiên sẽ ngắt khoá tất cả các chính sách tiếp theo. Tất cả các thông báo `instruct` được tích lũy và gửi cùng nhau.
+</Note>
+
+---
+
+## Nhập transitive
+
+Các tệp chính sách tùy chỉnh có thể nhập các mô-đun cục bộ bằng cách sử dụng đường dẫn tương đối:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+Tất cả các nhập tương đối có thể tiếp cận từ tệp nhập được phân giải. Điều này được triển khai bằng cách viết lại các nhập `from "failproofai"` thành đường dẫn dist thực tế và tạo các tệp `.mjs` tạm thời để đảm bảo tương thích ESM.
+
+---
+
+## Lọc loại sự kiện
+
+Sử dụng `match.events` để giới hạn khi một chính sách kích hoạt:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Only fires when the session ends
+    // ctx.session.transcriptPath contains the full session log
+    return allow();
+  },
+});
+```
+
+Bỏ qua `match` hoàn toàn để kích hoạt trên mọi loại sự kiện.
+
+---
+
+## Xử lý lỗi và chế độ lỗi
+
+Chính sách tùy chỉnh là **fail-open**: các lỗi không bao giờ chặn chính sách tích hợp hoặc làm hỏng trình xử lý hook.
+
+| Lỗi | Hành vi |
+|-----|--------|
+| `customPoliciesPath` không được đặt | Không có chính sách tùy chỉnh rõ ràng chạy; chính sách quy ước và tích hợp tiếp tục bình thường |
+| Tệp không tìm thấy | Cảnh báo được ghi vào `~/.failproofai/hook.log`; tích hợp tiếp tục |
+| Lỗi cú pháp/nhập (rõ ràng) | Lỗi được ghi vào `~/.failproofai/hook.log`; chính sách tùy chỉnh rõ ràng bị bỏ qua |
+| Lỗi cú pháp/nhập (quy ước) | Lỗi được ghi; tệp đó bị bỏ qua, các tệp quy ước khác vẫn tải |
+| `fn` ném tại thời gian chạy | Lỗi được ghi; hook đó được coi là `allow`; các hook khác tiếp tục |
+| `fn` mất lâu hơn 10 giây | Timeout được ghi; được coi là `allow` |
+| Thư mục quy ước bị thiếu | Không có chính sách quy ước chạy; không có lỗi |
+
+<Tip>
+Để gỡ lỗi các lỗi chính sách tùy chỉnh, hãy theo dõi tệp nhật ký:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Ví dụ đầy đủ: nhiều chính sách
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Prevent agent from writing to secrets/ directory
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// Keep the agent on track: verify tests before committing
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// Prevent unplanned dependency changes during freeze
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## Ví dụ
+
+Thư mục `examples/` chứa các tệp chính sách sẵn sàng để chạy:
+
+| Tệp | Nội dung |
+|-----|---------|
+| `examples/policies-basic.js` | Năm chính sách khởi động bao gồm các chế độ lỗi agent phổ biến |
+| `examples/policies-advanced/index.js` | Mô hình nâng cao: nhập transitive, gọi không đồng bộ, làm sạch đầu ra, và hook kết thúc phiên |
+| `examples/convention-policies/security-policies.mjs` | Chính sách bảo mật dựa trên quy ước (chặn ghi .env, ngăn chặn viết lại lịch sử git) |
+| `examples/convention-policies/workflow-policies.mjs` | Chính sách quy trình làm việc dựa trên quy ước (nhắc nhở kiểm tra, tệp ghi kiểm toán) |
+
+### Sử dụng các ví dụ tệp rõ ràng
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Sử dụng các ví dụ dựa trên quy ước
+
+```bash
+# Copy to project level
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Or copy to user level
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Không cần lệnh cài đặt — các tệp sẽ được chọn tự động khi sự kiện hook tiếp theo.