תצורה

​

היקפי תצורה

​

כללי מיזוג

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

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← deduplicated union

project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project wins, global ignored

project:  (no block-sudo entry)
local:    (no block-sudo entry)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← falls through to global

​

פורמט קובץ קונפיגורציה

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

​

הפניה לשדות

​

enabledPolicies

​

policyParams

​

hint (cross-cutting)

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

​

customPoliciesPath

​

כללים מבוססי קונבנציה

​

llm

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

​

ניהול תצורה מה-CLI

• הגדרות סוכן CLI — אומר לסוכן להתקשר failproofai --hook <event> בכל שימוש בכלי:
  • Claude Code: ~/.claude/settings.json (user), <cwd>/.claude/settings.json (project), <cwd>/.claude/settings.local.json (local)
  • OpenAI Codex: ~/.codex/hooks.json (user), <cwd>/.codex/hooks.json (project) — Codex אין לו היקף local
  • GitHub Copilot CLI (beta): ~/.copilot/hooks/failproofai.json (user), <cwd>/.github/hooks/failproofai.json (project) — Copilot אין לו היקף local. ערכי Hook משתמשים בשדות הפקודה bash/powershell של Copilot עם timeoutSec; הקובץ נושא סימן version: 1 ברמה עליונה. תמיכת Copilot CLI היא beta בזמן שאנו מאמתים את סכמת רשומות events.jsonl (שהתיעוד הציבורי אינו מציין) מול יותר הפעלות בעולם האמיתי.
  • Cursor Agent (beta): ~/.cursor/hooks.json (user), <cwd>/.cursor/hooks.json (project) — Cursor אין לו היקף local. ערכי Hook משתמשים בצורה {type, command, timeout} בצורת Claude (אין חלוקה bash/powershell), אך מאוחסנים תחת מפתחות אירוע camelCase (preToolUse, beforeSubmitPrompt, …) במערך שטוח לפי סכמת hooks של Cursor; הקובץ נושא סימן version: 1 ברמה עליונה. המטפל קנוני camelCase → PascalCase דרך CURSOR_EVENT_MAP כך שכללים מובנים קיימים יורים ללא שינוי. תמיכת Cursor Agent היא beta בזמן שאנו מאמתים את תמלול של Cursor על דיסק (לא מצוין בתיעוד הציבורי) מול יותר התקנות בעולם האמיתי.
  • OpenCode (beta): ~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs (user), <cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs (project) — OpenCode אין לו היקף local. בניגוד לשישת ה-CLIs האחרים, OpenCode אין לו מערכת hook חיצונית: הוא טוען בתהליך JS/TS plugins שנרשמו במפורש דרך המערך plugin: [] ב-opencode.json (auto-discovery מ-.opencode/plugins/ אינו כיצד plugins טוענים ב-opencode v1.14.33). Install טוען קובץ זעיר שנוצר של plugin שקורא subprocess לבינארי failproofai ותורגם את התגובה JSON של הבינארי חזרה לסמנטיקה של plugin: throw new Error() להכחשת אירוע כלי (מבטל את קריאת הכלי), client.session.prompt(...) עבור instruct וגם עבור Stop / SubagentStop deny (שולח את סיבת ההכחשה כהודעת המשתמש הבאה — ערוץ force-retry היחיד מאז session.idle הוא notification-only והשלכת זה אינו פעולה), ו-no-op לאפשרות. קובץ קנוני שם של כלי (lowercase → PascalCase דרך OPENCODE_TOOL_MAP) וקלידי arg של כניסת כלי (camelCase → snake_case דרך OPENCODE_TOOL_INPUT_MAP עבור Read / Write / Edit, למשל filePath → file_path, oldString → old_string) לפני שידור לבינארי, כך שבנויים של בדיקת נתיב כמו block-read-outside-cwd, block-env-files, ו-block-secrets-write יורים ללא שינוי על קריאות כלי OpenCode. הפעלות חיות בבסיס נתונים SQLite של opencode ב-~/.local/share/opencode/opencode.db; מערכת הדפים של הלוח קוראת אותם דרך opencode db --format json ו-opencode export <id>. תמיכת OpenCode היא beta בזמן שאנו מאמתים התנהגות בחדוות וגרסאות מול יותר הפעלות בעולם האמיתי. ראה את תיעוד plugins של OpenCode.
  • Pi (beta): ~/.pi/agent/settings.json (user), <cwd>/.pi/settings.json (project) — Pi אין לו היקף local. Pi טוען חבילות הרחבה TypeScript בעת ההפעלה; הקובץ הגדרות הוא מערך string שטוח {"packages": ["./relative/path", …]}. failproofai כותב ערך מערך packages אחד המצביע על ספרייה pi-extension/ משובצת שלו. ההרחבה מבחינים פנימיים במחזור subscriptions של Pi כדי tool_call / user_bash / input / session_start ופירות לתוך failproofai --hook <Event> --cli pi; המטפל קנוני underscore_lower_snake_case → PascalCase דרך PI_EVENT_MAP כך שכללים מובנים קיימים יורים ללא שינוי. קלידי arg של כניסת כלי גם קנוניים דרך PI_TOOL_INPUT_MAP (Pi’s Read / Write / Edit מסירה path רמוק מאשר file_path; קלידי המפתח העליון מאפשר block-env-files ו-block-secrets-write לירות — block-read-outside-cwd כבר היה path fallback). תמיכת Pi היא beta בזמן שעומדת ל-stabilize.
  • Gemini CLI (beta): ~/.gemini/settings.json (user), <cwd>/.gemini/settings.json (project) — Gemini אין לו היקף local (הוא מתעד היקף system ב-/etc/gemini-cli/settings.json אשר failproofai לא חשוף). Hook entries משתמשים בצורה {type, command, timeout} של Claude עטופה בסכמת matcher של Gemini {matcher, hooks: [...]} עם matcher: "*" כברירת מחדל. אירועים הם PascalCase (SessionStart, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification, SessionEnd); המטפל ממפה לשמות קנוניים של Claude דרך GEMINI_EVENT_MAP. שמות כלים הם snake_case (run_shell_command, read_file, write_file, replace, …) — המטפל מקנוני דרך GEMINI_TOOL_MAP כך שכללים מובנים קיימים יורים ללא שינוי. משקיף מדיניות משיג צורה שטוחה של Gemini {decision: "deny", reason} (מועדפת לכל Golden Rule exit-0 של Gemini), {hookSpecificOutput: {hookEventName, additionalContext}} להזרקת הקשר ב-BeforeAgent / AfterTool / SessionStart, ו-{decision: "block", reason} ב-AfterAgent לסמנטיקה force-retry. תמיכת Gemini CLI היא beta בזמן שאנו מגדילים כיסוי בעולם האמיתי. ראה את תיעוד hooks של Gemini CLI.
• policies-config.json — אומר ל-failproofai אילו כללים להעריך וויים פרמטרים (משותף בכל סוכני CLI)

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

• CLI אחד detected — בחר אוטומטי את זה CLI ללא הנמקה.
• מספר CLIs detected בטרמינל אינטראקטיבי — מציג בחירה יחידה במקלדת בחצים מקובצת לחלק Detected (N) (עם שורה מצטברת Install for all N detected + כל CLI detected בנפרד) וחלק Not installed (M) · install hooks ahead of time רשימה כל CLI שלא detected כאפשרות forward-install (↑↓ להעברה, Enter לבחירה, ^C לצאת). זרימת ה-uninstall מציגה רק את חלק Detected.
• מספר CLIs detected בריצה לא אינטראקטיבית (CI, no TTY) — מתקן להמון detected CLIs ללא הנמקה.
• None detected — חוזר ל-claude, עם אזהרה שלא binary agent נמצא ב-PATH; פקודת hook עדיין כתובה כך היא מופעלת ברגע שאתה מתקן אחד.

​

דוגמה: תצורה ברמת פרויקט עם ברירות מחדל של צוות

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