Cấu hình

​

Các phạm vi cấu hình

​

Quy tắc hợp nhất

project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← hợp đã khử trùng

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

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 vào global

​

Định dạng tệp cấu hình

{
  "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

​

policyParams

​

hint (cross-cutting)

{
  "policyParams": {
    "block-force-push": {
      "hint": "Hãy thử tạo một nhánh mới."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Sử dụng apt-get trực tiếp mà không cần sudo."
    },
    "custom/my-policy": {
      "hint": "Yêu cầu sự phê duyệt của người dùng trước."
    }
  }
}

​

customPoliciesPath

​

Các chính sách dựa trên quy ước

​

llm

{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​

Quản lý cấu hình từ CLI

• Cài đặt Agent CLI — yêu cầu agent gọi failproofai --hook <event> trên mỗi sử dụng công cụ:
  • Claude Code: ~/.claude/settings.json (người dùng), <cwd>/.claude/settings.json (dự án), <cwd>/.claude/settings.local.json (cục bộ)
  • OpenAI Codex: ~/.codex/hooks.json (người dùng), <cwd>/.codex/hooks.json (dự án) — Codex không có phạm vi local
  • GitHub Copilot CLI (beta): ~/.copilot/hooks/failproofai.json (người dùng), <cwd>/.github/hooks/failproofai.json (dự án) — Copilot không có phạm vi local. Các mục hook sử dụng các trường lệnh bash/powershell được xác định theo hệ điều hành của Copilot với timeoutSec; tệp mang một đánh dấu version: 1 cấp cao nhất. Hỗ trợ Copilot CLI là beta trong khi chúng tôi xác minh lược đồ bản ghi events.jsonl (mà các tài liệu công khai không chỉ định) so với các phiên làm việc thực tế hơn.
  • Cursor Agent (beta): ~/.cursor/hooks.json (người dùng), <cwd>/.cursor/hooks.json (dự án) — Cursor không có phạm vi local. Các mục hook sử dụng hình thức {type, command, timeout} dạng Claude (không chia bash/powershell), nhưng được lưu trữ dưới các khóa sự kiện camelCase (preToolUse, beforeSubmitPrompt, …) trong một mảng phẳng theo hooks schema của Cursor; tệp mang một đánh dấu version: 1 cấp cao nhất. Trình xử lý chính tắc hóa camelCase → PascalCase thông qua CURSOR_EVENT_MAP để các chính sách tích hợp sẵn hiện có kích hoạt không thay đổi. Hỗ trợ Cursor Agent là beta trong khi chúng tôi xác minh định dạng bảng điểm của Cursor trên đĩa (không được chỉ định trong tài liệu công khai) so với nhiều bản cài đặt thực tế hơn.
  • OpenCode (beta): ~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs (người dùng), <cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs (dự án) — OpenCode không có phạm vi local. Không giống như sáu CLI khác, OpenCode không có hệ thống hook lệnh bên ngoài: nó tải các plugin JS/TS trong quy trình được đăng ký rõ ràng qua mảng plugin: [] trong opencode.json (tự động khám phá từ .opencode/plugins/ không phải cách các plugin được tải trên opencode v1.14.33). Install thả một shim plugin nhỏ được tạo ra gọi lệnh phụ vào nhị phân failproofai và dịch phản hồi JSON dạng Claude của nhị phân trở lại ngữ semantics plugin: throw new Error() để từ chối sự kiện công cụ (hủy lệnh gọi công cụ), client.session.prompt(...) để instruct VÀ để từ chối Stop / SubagentStop (gửi lý do từ chối làm thông điệp người dùng tiếp theo — kênh retry-buộc duy nhất vì session.idle chỉ là thông báo và ném từ nó là no-op), và no-op cho phép. Shim chính tắc hóa cả tên công cụ (chữ thường → PascalCase qua OPENCODE_TOOL_MAP) và các khóa đối số đầu vào công cụ (camelCase → snake_case qua OPENCODE_TOOL_INPUT_MAP cho Read / Write / Edit, ví dụ: filePath → file_path, oldString → old_string) trước khi chuyển tiếp đến nhị phân, vì vậy các chính sách kiểm tra đường dẫn tích hợp sẵn như block-read-outside-cwd, block-env-files, và block-secrets-write kích hoạt không thay đổi trên các lệnh gọi công cụ OpenCode. Các phiên sống trong cơ sở dữ liệu SQLite của opencode tại ~/.local/share/opencode/opencode.db; trình xem phiên của bảng điều khiển đọc chúng qua opencode db --format json và opencode export <id>. Hỗ trợ OpenCode là beta trong khi chúng tôi xác minh hành vi trên các phiên bản và so với nhiều phiên làm việc thực tế hơn. Xem tài liệu plugin OpenCode.
  • Pi (beta): ~/.pi/agent/settings.json (người dùng), <cwd>/.pi/settings.json (dự án) — Pi không có phạm vi local. Pi tải các gói mở rộng TypeScript khi khởi động; tệp cài đặt là một mảng chuỗi phẳng {"packages": ["./relative/path", …]}. failproofai ghi một mục mảng gói duy nhất trỏ vào thư mục pi-extension/ được đóng gói của nó. Phần mở rộng trội theo dõi các sự kiện tool_call / user_bash / input / session_start của Pi và lệnh shell tới failproofai --hook <Event> --cli pi; trình xử lý chính tắc hóa underscore_lower_snake_case → PascalCase thông qua PI_EVENT_MAP để các chính sách tích hợp sẵn hiện có kích hoạt không thay đổi. Các đối số đầu vào công cụ cũng được chính tắc hóa qua PI_TOOL_INPUT_MAP (Pi’s Read / Write / Edit giao path thay vì file_path; ánh xạ khóa cấp cao nhất cho phép block-env-files và block-secrets-write kích hoạt — block-read-outside-cwd đã có một dự phòng path). Hỗ trợ Pi là beta trong khi API mở rộng Pi và bố cục nhật ký phiên ổn định.
  • Gemini CLI (beta): ~/.gemini/settings.json (người dùng), <cwd>/.gemini/settings.json (dự án) — Gemini không có phạm vi local (nó ghi lại một phạm vi system tại /etc/gemini-cli/settings.json mà failproofai không hiển thị). Các mục hook sử dụng hình thức {type, command, timeout} của Claude được bao bọc trong lược đồ bộ khớp {matcher, hooks: [...]} của Gemini với matcher: "*" theo mặc định. Các sự kiện là PascalCase (SessionStart, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification, SessionEnd); trình xử lý ánh xạ tới các tên canonical Claude qua GEMINI_EVENT_MAP. Tên công cụ là snake_case (run_shell_command, read_file, write_file, replace, …) — trình xử lý chính tắc hóa qua GEMINI_TOOL_MAP để các chính sách tích hợp sẵn hiện có kích hoạt không thay đổi. Đánh giá chính sách phát ra hình dạng phẳng {decision: "deny", reason} của Gemini (ưa thích theo “Golden Rule” hợp đồng exit-0 của Gemini), {hookSpecificOutput: {hookEventName, additionalContext}} để tiêm bối cảnh trên BeforeAgent / AfterTool / SessionStart, và {decision: "block", reason} trên AfterAgent để sử dụng ngữ semantics retry-buộc. Hỗ trợ Gemini CLI là beta trong khi chúng tôi mở rộng độ bao phủ thực tế. Xem tài liệu hooks Gemini CLI.
• 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 (dùng chung trên tất cả các CLI agent)

failproofai policies --install --cli codex --scope project
failproofai policies --install --cli copilot --scope project
failproofai policies --install --cli cursor --scope project
failproofai policies --install --cli opencode --scope project
failproofai policies --install --cli pi --scope project
failproofai policies --install --cli gemini --scope project
failproofai policies --install --cli claude codex copilot cursor opencode pi gemini

• Một CLI được phát hiện — tự động chọn CLI đó mà không cần nhắc.
• Nhiều CLI được phát hiện trong terminal tương tác — hiển thị lời nhắc chọn đơn với phím mũi tên được nhóm thành một phần Detected (N) (với một hàng tổng hợp Install for all N detected + từng CLI được phát hiện riêng lẻ) và một phần Not installed (M) · install hooks ahead of time liệt kê mọi CLI được hỗ trợ chưa được phát hiện như một tùy chọn cài đặt phía trước (↑↓ để di chuyển, Enter để chọn, ^C để thoát). Luồng gỡ cài đặt chỉ hiển thị phần Detected.
• Nhiều CLI được phát hiện trong lần chạy không tương tác (CI, không TTY) — cài đặt cho tất cả các CLI được phát hiện mà không cần nhắc.
• Không có cái nào được phát hiện — quay trở lại claude, với cảnh báo rằng không tìm thấy nhị phân agent nào trong PATH; lệnh hook vẫn được ghi để nó kích hoạt ngay khi bạn cài đặt một lệnh.

​

Ví dụ: cấu hình cấp dự án có giá trị mặc định nhóm

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}