failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/he/configuration.mdx

@@ -0,0 +1,264 @@
+---
+title: הגדרות
+description: "פורמט קובץ תצורה, מערכת שלוש-ההיקפים, וכללי ההיזוגה"
+icon: gear
+---
+
+failproofai משתמש בקבצי תצורה JSON כדי לשלוט איזו מדיניות פעילה, כיצד היא מתנהגת, ומאיפה מדיניות מותאמת אישית נטענת. התצורה תוכננה להיות קלה לשיתוף עם הצוות שלך - בצע commit אל הריפו שלך וכל מפתח יקבל את אותה רשת ביטחון לאירוח.
+
+---
+
+## היקפי התצורה
+
+יש שלוש היקפי תצורה, המוערכות לפי סדר עדיפויות:
+
+| היקף | נתיב קובץ | מטרה |
+|-------|-----------|---------|
+| **project** | `.failproofai/policies-config.json` | הגדרות לפי ריפו, committed לשליטה בגרסה |
+| **local** | `.failproofai/policies-config.local.json` | דריסות אישיות לפי ריפו, gitignored |
+| **global** | `~/.failproofai/policies-config.json` | ברירות מחדל ברמת משתמש בכל הפרויקטים |
+
+כאשר failproofai מקבל אירוע hook, הוא טוען ומזגג את כל שלושת הקבצים שקיימים עבור ספריית העבודה הנוכחית.
+
+### כללי ההיזוגה
+
+**`enabledPolicies`** - האיחוד של כל שלושת ההיקפים. מדיניות שמופעלת בכל רמה היא פעילה.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← איחוד עם הסרת כפילויות
+```
+
+**`policyParams`** - ההיקף הראשון המגדיר פרמטרים למדיניות מסוימת מנצח לחלוטין. אין היזוגה עמוקה של ערכים בתוך הפרמטרים של מדיניות.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project מנצח, global מתעלם
+```
+
+```text
+project:  (אין ערך block-sudo)
+local:    (אין ערך block-sudo)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← נופל דרך ל-global
+```
+
+**`customPoliciesPaths` / `customPoliciesPath`** - ההיקף הראשון שמגדיר כל אחת מהצורות מנצח.
+
+**`disabledCustomPolicies`** - איחוד בכל ההיקפים. לוח המחוונים כותב כאן מזהה תו-מועד כאשר אתה כובה מדיניות בודדת מקובץ מדיניות מפורשי או מוסכמה. מדיניות שאינה רשומה נשארת מופעלת כברירת מחדל; המזהים כוללים את קובץ המקור כך שמדיניות בעלות אותו שם בקבצים מרובים יכולות להיות מנוהלות בהתאמה.
+
+**`llm`** - ההיקף הראשון שמגדיר אותו מנצח.
+
+---
+
+## פורמט קובץ התצורה
+
+```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"
+}
+```
+
+---
+
+## הפניית שדות
+
+### `enabledPolicies`
+
+Type: `string[]`
+
+רשימת שמות מדיניות להפעלה. השמות חייבים להתאים בדיוק לזיהויי המדיניות המוצגים על ידי `failproofai policies`. ראה [Built-in Policies](/he/built-in-policies) לקבלת הרשימה המלאה.
+
+מדיניות שאינה ב-`enabledPolicies` אינה פעילה, גם אם יש לה ערכים ב-`policyParams`.
+
+### `policyParams`
+
+Type: `Record<string, Record<string, unknown>>`
+
+דריסות פרמטרים לכל-מדיניות. המפתח החיצוני הוא שם המדיניות; המפתחות הפנימיים הם ספציפיים למדיניות. כל מדיניות מתעדת את הפרמטרים הזמינים שלה ב-[Built-in Policies](/he/built-in-policies).
+
+אם למדיניות יש פרמטרים אך אינך מציין אותם, משתמשים בברירות המחדל המובנות של המדיניות. משתמשים שאינם מגדירים `policyParams` כלל מקבלים התנהגות זהה לגרסאות קודמות.
+
+מפתחות לא ידועים בתוך בלוק הפרמטרים של מדיניות מתעלמים בשקט בעת הנחת hook אך מסומנים כאזהרות כשאתה מריץ `failproofai policies`.
+
+#### `hint` (חוצה-חתוך)
+
+Type: `string` (optional)
+
+הודעה המצורפת לסיבה כאשר מדיניות מחזירה `deny` או `instruct`. השתמש בה כדי לתן Claude הנחיות פעולות מבלי לשנות את המדיניות עצמה.
+
+פועל עם כל סוג מדיניות — מובנה, מותאמת אישית (`custom/`), מוסכמת פרויקט (`.failproofai-project/`), או מוסכמת משתמש (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "נסה ליצור ענף טרי במקום."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "השתמש ב-apt-get ישירות בלי sudo."
+    },
+    "custom/my-policy": {
+      "hint": "בקש אישור מהמשתמש תחילה."
+    }
+  }
+}
+```
+
+כאשר `block-force-push` דוחה, Claude רואה: *"Force-pushing חסום. נסה ליצור ענף טרי במקום."*
+
+ערכים שאינם מחרוזות ומחרוזות ריקות מתעלמות בשקט. אם `hint` לא מוגדר, ההתנהגות נשארת ללא שינוי (תאומה לאחור).
+
+### `customPoliciesPath`
+
+Type: `string` (absolute path)
+
+נתיב לקובץ JavaScript המכיל מדיניות hook מותאמות אישית. זה מוגדר באופן אוטומטי על ידי `failproofai policies --install --custom <path>` (הנתיב מעובד לערך מוחלט לפני שהוא מאוחסן).
+
+הקובץ נטען בחדשות בכל אירוע hook - אין שימוש במטמון. ראה [Custom Policies](/he/custom-policies) לפרטי כתיבה.
+
+### מדיניות מבוססת מוסכמה
+
+בנוסף ל-`customPoliciesPath` המפורשת, failproofai גוקם ובטוען קבצי מדיניות מספריות `.failproofai/policies/` באופן אוטומטי:
+
+| רמה | ספרייה | היקף |
+|-------|-----------|-------|
+| Project | `.failproofai/policies/` | משותפת עם צוות דרך שליטה בגרסה |
+| User | `~/.failproofai/policies/custom-policies/` | אישית, חלה על כל הפרויקטים |
+
+<Note>
+  ספריית הרמה השנייה עברה ברמה לתוך ספריית הבית כחלק מיצירת ארגון מחדש של ספריית הבית. קבצים שנותרו במיקום הישן `~/.failproofai/policies/` מועברים אל `custom-policies/` באופן אוטומטי בפעם הראשונה שאתה מריץ כל פקודת `failproofai` לאחר שדרוג, והפקודה אומרת לך אילו קבצים היא העבירה.
+</Note>
+
+**התאמת קובץ:** רק קבצים המתאימים `*policies.{js,mjs,ts}` נטענים (למשל `security-policies.mjs`, `workflow-policies.js`). קבצים אחרים בספרייה מתעלמים.
+
+**אין צורך בהגדרה:** מדיניות מוסכמה אינה דורשת ערכים ב-`policies-config.json`. פשוט שחרר קבצים לתוך הספרייה והם נוסקפו באירוע ה-hook הבא.
+
+**טעינת איחוד:** שתי ספריות מוסכמה של פרויקט ומשתמש סרוקות. כל הקבצים המתאימים משתי הרמות נטענים (בשונה מ-`customPoliciesPath` שמשתמש בה-first-scope-wins).
+
+ראה [Custom Policies](/he/custom-policies) לפרטים ודוגמאות נוספים.
+
+### `llm`
+
+Type: `object` (optional)
+
+הגדרות לקוח LLM עבור מדיניות שמבצעות קריאות AI. לא נדרש עבור רוב ההגדרות.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## ניהול התצורה מ-CLI
+
+הפקודות `policies --install` ו-`policies --uninstall` כותבות לקובץ הגדרות ה-hook של ה-CLI של אירוח שלך (נקודות הכניסה של ה-hook), בעוד ש-`policies-config.json` הוא הקובץ שאתה מנהל ישירות. השניים נפרדים:
+
+- **הגדרות Agent 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` (שהמסמכים הציבוריים לא מציינים) כנגד יותר מושבים בעולם האמיתי. **VS Code Copilot Chat agent mode (Preview)** קורא תצורות hook מ-`.github/hooks/*.json`, `~/.copilot/hooks/*.json`, ו-`~/.claude/settings.json` (מנוהל על ידי הגדרת `chat.hookFilesLocations`) תוך שימוש באותו חוזה בצורת Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — הנתיבים המדויקים שאליהם `failproofai policies --install --cli copilot` (או `--cli claude`) **כבר אוכפים ב-VS Code agent mode** ללא צורך באינטגרציה `vscode` נפרדת (מאומת בחי מרשמי הגילוי של VS Code).
+  - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `<cwd>/.cursor/hooks.json` (project) — Cursor אין לו היקף `local`. ערכי Hook משתמשים בצורה בצורת Claude `{type, command, timeout}` (אין פיצול `bash`/`powershell`), אך מאוחסנים תחת מפתחות אירוע camelCase (`preToolUse`, `beforeSubmitPrompt`, …) במערך שטוח לפי [schemas hooks](https://cursor.com/docs/hooks) של Cursor; הקובץ נושא סימן `version: 1` ברמה העליונה. מטפל canonicalizes camelCase → PascalCase דרך `CURSOR_EVENT_MAP` כך שמדיניות מובנה קיימת ללא שינוי. תמיכה ב-Cursor Agent היא **beta** בזמן שאנו מאמתים את דיווח הטרנסקריפט של Cursor on-disk (לא מצוין במסמכים הציבוריים) כנגד יותר התקנות בעולם האמיתי.
+  - **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 in-process שנרשמו בצורה מפורשת דרך מערך `plugin: []` ב-`opencode.json` (auto-discovery מ-`.opencode/plugins/` הוא **לא** איך plugins טוענים ב-opencode v1.14.33). Install משחרר shim plugin שנוצר קטן שמבצע subprocess-calls לבינארי failproofai ותרגום התגובה JSON בצורת Claude של הבינארי חזרה לסמנטיקה של plugin: `throw new Error()` עבור tool-event deny (מבטל את קריאת הכלי), `client.session.prompt(...)` עבור instruct וגם עבור `Stop` / `SubagentStop` deny (משחרר את סיבת ה-deny כהודעת המשתמש הבאה — ערוץ force-retry היחיד מאז `session.idle` הוא notification-only וזריקה מן זה היא no-op), ו-no-op עבור allow. Shim canonicalizes גם שמות כלי (lowercase → PascalCase דרך `OPENCODE_TOOL_MAP`) וגם tool-input arg keys (camelCase → snake_case דרך `OPENCODE_TOOL_INPUT_MAP` עבור `Read` / `Write` / `Edit`, למשל `filePath` → `file_path`, `oldString` → `old_string`) לפני שליחה לבינארי, כך שpath-checking builtins כמו `block-read-outside-cwd`, `block-env-files`, ו-`block-secrets-write` נורים ללא שינוי בקריאות כלי OpenCode. Sessions חיות בבסיס נתונים SQLite של opencode ב-`~/.local/share/opencode/opencode.db`; מצפה המושבים של לוח המחוונים קורא אותם דרך `opencode db --format json` ו-`opencode export <id>`. תמיכה ב-OpenCode היא **beta** בזמן שאנו מאמתים התנהגות בגרסאות ובמול יותר מושבים בעולם האמיתי. ראה [OpenCode plugins docs](https://opencode.ai/docs/plugins/).
+  - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `<cwd>/.pi/settings.json` (project) — Pi אין לו היקף `local`. Pi טוען TypeScript extension packages בעת ההפעלה; קובץ ההגדרות הוא מערך מחרוזות שטוח `{"packages": ["./relative/path", …]}`. failproofai כותב ערך packages-array יחיד המצביע על ספריית `pi-extension/` המופצצת שלו. ההרחבה פנימית מנויה לאירועי `tool_call` / `user_bash` / `input` / `session_start` של Pi ופגזי out to `failproofai --hook <Event> --cli pi`; מטפל canonicalizes underscore_lower_snake_case → PascalCase דרך `PI_EVENT_MAP` כך שמדיניות מובנה קיימת ללא שינוי. ארגומנטי tool input גם canonicalize דרך `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit deliver `path` במקום `file_path`; mapping the top-level key חושפת `block-env-files` ו-`block-secrets-write` — `block-read-outside-cwd` כבר היה בחזקת fallback `path`). תמיכה ב-Pi היא **beta** בזמן ש-API extension של Pi וסכמת session-log מתייצבות.
+  - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**user scope only** — Hermes אין לו תצורה project/local). Hermes הוא שער Slack/Telegram **gateway**, כך שהתקנה אחת מיירטת קריאות כלי מכל פלטפורמה (Slack/Telegram/cli/cron) **וגם** subagents פנימיים. ערכי Hook הם זוג `{command, timeout}` (timeout ב**שניות**) תחת מפת `hooks:` המקודדת לפי אירועי snake_case של Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); מטפל canonicalizes אירועים דרך `HERMES_EVENT_MAP` ושמות כלי דרך `HERMES_TOOL_MAP` כך שמדיניות מובנה נורות ללא שינוי. התצורה נערכת דרך יישור YAML `Document` המשמר הערות כך שהגדרות אחרות של האופרטור שורדות, והתקנה קובעת `hooks_auto_accept: true` כך שה-gateway headless (no TTY) מריץ את ה-hooks ללא בקשת הסכמה. המעריך פולט חוזה stdout של Hermes `{"decision":"block","reason"}` (Hermes מתעלם קודים יציאה). **Limitations:** Hermes אין turn-end `Stop` event, אז ה-`require-*-before-stop` builtins לא נורים עבורו (inapplicable, לא שבור); `instruct` נרדף כ-allow-with-logged-note (אין ערוץ context נוסף); וredaction סוד פלט (`sanitize-*`) לא יכול לשכתב tool output דרך חוזה shell-hook. Hermes הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את מושבי ה-gateway שלו ישירות מ-`~/.hermes/state.db`.
+  - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**user scope only** — OpenClaw אין לו תצורה project/local). כמו Hermes, OpenClaw הוא multi-channel self-hosted **gateway**, כך שהתקנה אחת מיירטת קריאות כלי מכל ערוץ ו-subagents פנימיים שלו. אוכיפה מריצה דרך **in-process plugin hooks** של OpenClaw (hook מבוססות קובץ פנימיים שלו הם תצפית בלבד ולא יכולים לחסום), כך ש — כמו OpenCode/Pi — failproofai משחרר ספרייה סטטית `openclaw-plugin/` שemulates-spawns את בינארי failproofai ותרגום הפסק. התקנה רושמת את ספרייה ה-plugin שנספקה בעמוד `plugins.load.paths[]` של `openclaw.json` וממקדת אותה תחת `plugins.entries.failproofai` (עם `hooks.allowConversationAccess: true`, נדרש עבור raw-conversation hooks). המעריך פולט פסק `{permission, reason}` שטוח וה-shim ממפה אותו לכל צורת החזרה של hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), ו-`before_agent_finalize → {action:"revise", reason}` (**Stop** — שער turn-end אמיתי, כך ש-`require-*-before-stop` builtins **אוכפים** ב-OpenClaw, בשונה מ-Hermes). אירועים ושמות כלי canonicalize binary-side דרך `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) כך שמדיניות מובנה נורות ללא שינוי; ה-shim נכשל פתוח בכל spawn/parse/timeout error. OpenClaw הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את מושבי JSONL שלו ב-`~/.openclaw/agents/<agentId>/sessions/<uuid>.jsonl`.
+  - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (user), `<cwd>/.factory/hooks.json` (project) — Factory אין לו היקף `local`. droid משחרר מערכת hook בעלת פקודה חיצונית בצורת Claude, אך עם שתי דקויות מאומתות בחיים כנגד droid v0.171.0: (1) שמות אירוע חיים ברמה **העליונה** של `hooks.json` — אין **אין wrapper `"hooks"`** (droid דוחה אחד); אירועי כלי (`PreToolUse`/`PostToolUse`) נושאים `"matcher": "*"`, אירועים שאינם כלים משמיטים אותו. (2) Deny מונע על ידי **exit code 2 של hook + stderr**, לא JSON decision — ענף `factory` של המעריך חוזר exit 2 עבור tool/prompt events ו-`{decision:"block", reason}` רק באירוע turn-end `Stop` (ערוץ force-retry היחיד של droid). אירועים כבר PascalCase (אין event map) והמטען הוא Claude snake_case; רק שמות כלי canonicalize דרך `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את מושבי on-disk JSONL שלו ב-`~/.factory/sessions/<encoded-cwd>/<sessionId>.jsonl`.
+  - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (user), `<cwd>/.devin/config.json` (project) — Devin אין לו היקף `local`. Devin הוא **pure Claude-clone** מאומת בחיים כנגד devin v3000.1.27: הוא משתמש בסכמת Claude `"hooks"`-wrapper סטנדרטית (כתיבה משמרות-merge כך שהמפתחות האחרים של קובץ ההגדרות — `org_id`, `theme_mode`, … — שורדות), שמות אירועים כבר-PascalCase (אין event map, אין handler branch), ופלט stdin בצורת Claude snake_case (ללא normalization). ענף `devin` של המעריך דוחה עם `{"decision":"block","reason"}` JSON ב-stdout ב-exit 0 עבור **כל** אירוע (מאומת — הבלוק דרס `--permission-mode dangerous`); באירוע turn-end `Stop` הסיבה נושאת את הניסוח force-retry של MANDATORY-ACTION כך שה-`require-*-before-stop` builtins אוכפים. רק שמות כלי canonicalize דרך `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` כבר canonical). Devin הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את מושבי SQLite שלו ב-`~/.local/share/devin/cli/sessions.db` (כל שורת `sessions` נושאת `working_directory` אמיתי, כך שמושבים מקובצים לפי cwd פרויקט כמו Claude).
+  - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (user), `<cwd>/.agents/hooks.json` (project) — Antigravity אין לו היקף `local`. בשונה מ-Factory/Devin, Antigravity יש שלו **חוזה** (לא Claude-clone), מאומת בחיים כנגד agy v1.1.2. `hooks.json` משתמש בסכמה **named-hook**: המפתח ברמה העליונה הוא שם hook *name* (`"failproofai"`) שערכו הוא אירוע→handlers map — אירועי כלי (`PreToolUse`/`PostToolUse`) מטפלים עטוף בחוזה `{matcher:"*", hooks:[…]}`, בעוד `PreInvocation`/`Stop` הם **flat** arrays של מטפלים (hook שמות אחרים משומרים). המטען stdin הוא **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai ממנורמל אותו ל-snake_case לפני פעולת מדיניות, וממפה PascalCase args של `run_command` (`CommandLine`/`Cwd`) דרך `ANTIGRAVITY_TOOL_INPUT_MAP`. ענף `antigravity` של המעריך משתמש בצורות תגובה **שלו** של Antigravity: `{decision:"deny", reason}` חוסם tool/prompt (exit 0), `{decision:"continue", reason}` באירוע turn-end `Stop` enters the loop (כך ש-`require-*-before-stop` builtins אוכפים), ו-`{injectSteps:[{ephemeralMessage}]}` injects הנחיה ב-`PreInvocation` (→ `UserPromptSubmit`). שמות כלי canonicalize דרך `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את תמלילים plain-JSONL שלו ב-`~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl` (conversation index ב-`conversation_summaries.db`).
+  - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (user), `<cwd>/.agents/plugins/failproofai/hooks/hooks.json` (project) — Goose אין לו היקף `local`. אוכיפה משתמשת בסביבת **hooks** של Goose, ה-cross-agent **Open Plugins** spec: המתקין פשוט שחרר את ספרייה `failproofai` plugin וGoose auto-discovers אותו בעת ההפעלה (self-registering אותו לתוך `~/.config/goose/config.yaml`). ה-`hooks.json` משתמש בסכמה Open Plugins **עם** wrapper `"hooks"` ברמה העליונה, ו-matcher הוא **omitted** בכל אירוע — `"*"` חשוף הוא regex לא תקף שתואם כלום (מאומת בחיים כנגד goose v1.43.0). שמות אירוע כבר PascalCase (אין event map); המטען stdin משתמש בـ `event`/`working_dir`, שהמטפל ממנורמל ל-`hook_event_name`/`cwd`. ענף `goose` של המעריך דוחה עם `{"decision":"block","reason"}` JSON ב-stdout ב-exit 0, מכובד ב**`PreToolUse`** אירוע בלבד (משחרר ב-goose ≥ v1.37.0) — שנורה עבור כלי ה-shell **וגם בתוך subagents משותקים**, כך שהוא נקודת deny יחידה מספיקה; כל hook אחר error נכשל **open**. Goose אין **אין `Stop` event**, כך שה-`require-*-before-stop` builtins לא חלים (כמו עם Hermes). שמות כלי canonicalize דרך `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) ופתח keys דרך `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את מושבי SQLite שלו ב-`~/.local/share/goose/sessions/sessions.db` (כל שורת `sessions` נושאת `working_dir` אמיתי, כך שמושבים מקובצים לפי cwd פרויקט כמו Devin; `--no-session` scratch runs מסוננים).
+- **`policies-config.json`** — אומר ל-failproofai איזו מדיניות להעריך ועם מה פרמטרים (משותפת בכל אירוח CLIs)
+
+עבור `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` עבור יעד אירוח ספציפי (space-separated או חזר עבור כל תת-סט):
+
+```bash
+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 hermes --scope user
+failproofai policies --install --cli openclaw --scope user
+failproofai policies --install --cli factory --scope project
+failproofai policies --install --cli devin --scope project
+failproofai policies --install --cli antigravity --scope project
+failproofai policies --install --cli goose --scope project
+failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose
+```
+
+כאשר `--cli` משמיט, `failproofai` גוקם אי אירוח CLIs מותקנים (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`):
+
+- **CLI אחד גוקם** — auto-selects את ה-CLI בלי בקשה.
+- **ריבויים CLIs גוקמים** בטרמינל אינטראקטיבי — מציג prompt single-select המונע על ידי arrow-key מקובץ לתוך `Detected (N)` section (עם `Install for all N detected` aggregate row + כל CLI גוקם בנפרד) ו`Not installed (M) · install hooks ahead of time` section מפרט כל CLI חסר כאפשרות forward-install (↑↓ לתנוע, Enter לבחור, ^C לסגור). זרימת ה-uninstall מציגה רק את סעיף ה-Detected.
+- **ריבויים CLIs גוקמים** בריצה non-interactive (CI, no TTY) — התקנות עבור כל CLIs גוקמים בלי בקשה.
+- **אף אחד לא גוקם** — נופל חזרה ל-`claude`, עם אזהרה שאין בינארי אירוח בـ PATH; פקודת ה-hook עדיין כתובה כך שהיא מופעלת ברגע שתתקין אחד.
+
+אתה יכול לערוך `policies-config.json` ישירות בכל עת; שינויים נכנסים לתוקף מיידית באירוע ה-hook הבא ללא צורך ב-restart.
+
+---
+
+## דוגמה: תצורה ברמת פרויקט עם ברירות מחדל צוות
+
+Commit `.failproofai/policies-config.json` לריפו שלך:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+כל מפתח יכול לאחר מכן ליצור `.failproofai/policies-config.local.json` (gitignored) עבור דריסות אישיות ללא השפעה על חברי צוות.

package/.next/standalone/docs-old/he/custom-policies.mdx

@@ -0,0 +1,359 @@
+---
+---
+title: מדיניות מותאמות אישית
+description: "כתוב את הכללים שלך ב-JavaScript - אכוף כללים פרויקטיים, מנע סטיות, זהה כשלים, השתלב עם מערכות חיצוניות"
+icon: code
+---
+
+מדיניות מותאמת אישית מאפשרת לך לכתוב כללים לכל התנהגות של agent: אכוף כללים פרויקטיים, מנע סטיות, חסום פעולות הרסניות, זהה agents שתקועים, או השתלב עם Slack, זרימות אישור, ועוד. הם משתמשים באותו מערכת hook של אירועים וקביעות `allow`, `deny`, `instruct` כמו מדיניות מובנית.
+
+---
+
+## דוגמה מהירה
+
+```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();
+  },
+});
+```
+
+התקנה:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## שתי דרכים לטעון מדיניות מותאמת אישית
+
+### אפשרות 1: מבוססת על כללי כתיבה (מומלץ)
+
+זרוק קבצי `*policies.{js,mjs,ts}` ל-`.failproofai/policies/` והם יטעונו באופן אוטומטי — אין צורך בדגלים או שינויים בתצורה. זה עובד כמו git hooks: זרוק קובץ, וזה פשוט עובד.
+
+```
+# ברמת הפרויקט — מתוקן ל-git, משותף עם הצוות
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# ברמת המשתמש — אישי, חל על כל הפרויקטים
+~/.failproofai/policies/my-policies.mjs
+```
+
+**איך זה עובד:**
+- שתי ספריות (פרויקט ומשתמש) נסרקות (union — לא first-scope-wins)
+- קבצים נטענים בסדר אלפביתי בכל ספרייה. הוסף `01-`, `02-` כדי לשלוט בסדר
+- רק קבצים תואמים `*policies.{js,mjs,ts}` נטענים; קבצים אחרים מתעלמים
+- כל קובץ נטען בעצמאות (fail-open לכל קובץ)
+- עובד לצד `--custom` מפורש ומדיניות מובנית
+
+<Tip>
+מדיניות כללי כתיבה היא הדרך הקלה ביותר לבנות תקן איכות עבור הארגון שלך. קבע `.failproofai/policies/` ל-git וכל חברה בצוות מקבלת את אותם כללים באופן אוטומטי — אין צורך בהגדרה לכל מפתח. כאשר הצוות שלך מגלה מצבי כשל חדשים, הוסף מדיניות ודחוף. עם הזמן אלה הופכות לתקן איכות חי המשתפר עם כל תרומה.
+</Tip>
+
+### אפשרות 2: נתיב קובץ מפורש
+
+```bash
+# התקנה עם קובץ מדיניות מותאמת אישית
+failproofai policies --install --custom ./my-policies.js
+
+# החלף את נתיבי המדיניות המותאמת אישית
+failproofai policies --install --custom ./new-policies.js
+
+# קביעת תצורה של קבצים מפורשים מרובים (טעונים בסדר דגלים)
+failproofai policies --install --custom ./security.js --custom ./workflow.js
+
+# הסר את כל נתיבי המדיניות המותאמת אישית המפורשים מהתצורה
+failproofai policies --uninstall --custom
+```
+
+נתיבים מוחלטים מורכבים מאוחסנים ב-`policies-config.json` כ-`customPoliciesPaths`. חזור על `--custom` כדי לקבוע תצורה של קבצים מרובים. תצורות קיימות המשתמשות בשדה `customPoliciesPath` של העבר ממשיכות לעבוד. קבצים נטענים מחדש בכל אירוע hook - אין קאשינג בין אירועים.
+
+כל מדיניות רשומה מופיעה עם ההפעלה/כיבוי שלה בלוח הבקרה. החלפת מדיניות כיבה מתעדת את ה-ID המיומן בקובץ שלה ב-`disabledCustomPolicies`; הקובץ והמדיניות האחרות שלו ממשיכים להטען, בעוד המדיניות המבוטלת מחוצה לחוץ לפני תאימות אירוע. שמות מדיניות משוכפלים בקבצים שונים הם בעלי הפעלה/כיבוי בלתי תלוי.
+
+### שימוש בשניהם ביחד
+
+מדיניות כללי כתיבה וקבצי `--custom` מפורשים יכולים להתקיים. סדר טעינה:
+
+1. קבצי `customPoliciesPaths` מפורשים (בסדר מוקביע)
+2. קבצי כללי כתיבה של פרויקט (`{cwd}/.failproofai/policies/`, אלפביתי)
+3. קבצי כללי כתיבה של משתמש (`~/.failproofai/policies/`, אלפביתי)
+
+---
+
+## API
+
+### ייבוא
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+רושם מדיניות. קרא לזה כמה פעמים לפי הצורך עבור מדיניות מרובות באותו קובץ.
+
+```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>;
+});
+```
+
+### עוזרי קביעת החלטה
+
+| פונקציה | השפעה | השתמש כאשר |
+|----------|--------|----------|
+| `allow()` | אפשר את הפעולה בשתיקה | הפעולה בטוחה, לא נדרשת הודעה |
+| `deny(message)` | חסום את הפעולה | ה-agent לא צריך לבצע פעולה זו |
+| `instruct(message)` | הוסף הקשר ללא חסימה | תן ל-agent הקשר נוסף להישאר על המסלול |
+
+`deny(message)` - ההודעה מופיעה ל-Claude עם קידומת `"Blocked by failproofai:"`. `deny` אחד מקצר את כל ההערכה הנוספת.
+
+`instruct(message)` - ההודעה מוצמדת להקשר של Claude עבור קריאת הכלי הנוכחית. כל הודעות `instruct` מצטברות ומסופקות ביחד.
+
+<Tip>
+אתה יכול להוסיף הנחיות נוספות לכל הודעת `deny` או `instruct` על ידי הוספת שדה `hint` ב-`policyParams` — אין צורך בשינוי קוד. זה עובד גם עבור מדיניות מותאמת אישית (`custom/`), כללי כתיבה של פרויקט (`.failproofai-project/`), וכללי כתיבה של משתמש (`.failproofai-user/`). ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים.
+</Tip>
+
+### הודעות allow מידע
+
+`allow(message)` מאפשר את הפעולה **וגם** שולח הודעה מידע חזרה ל-Claude. ההודעה מסופקת כ-`additionalContext` בתגובת stdout של מטפל hook — אותו מנגנון המשמש ל-`instruct`, אך שונה מבחינה סמנטית: זה עדכון סטטוס, לא אזהרה.
+
+| פונקציה | השפעה | השתמש כאשר |
+|----------|--------|----------|
+| `allow(message)` | אפשר ושלח הקשר ל-Claude | אשר בדיקה עברה, או הסבר מדוע בדיקה דילגה |
+
+מקרי שימוש:
+- **אישורי סטטוס:** `allow("All CI checks passed.")` — אומר ל-Claude שהכל ירוק
+- **הסברי fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — אומר ל-Claude מדוע בדיקה דילגה כך שיש לו הקשר מלא
+- **הודעות מרובות מצטברות:** אם מדיניות מרובות כל אחת מחזירה `allow(message)`, כל ההודעות מצורפות עם שורות חדשות ומסופקות ביחד
+
+```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.");
+  },
+});
+```
+
+### שדות `PolicyContext`
+
+| שדה | סוג | תיאור |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | הכלי שמופעל (למ"ג `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | פרמטרי הקלט של הכלי |
+| `payload` | `Record<string, unknown>` | עומס אירוע גולמי מלא מ-Claude Code |
+| `session` | `SessionMetadata \| undefined` | הקשר מפגש (ראה למטה) |
+
+### שדות `SessionMetadata`
+
+| שדה | סוג | תיאור |
+|-------|------|-------------|
+| `sessionId` | `string` | Claude Code מזהה מפגש |
+| `cwd` | `string` | ספריה עובדת של מפגש Claude Code |
+| `transcriptPath` | `string` | נתיב לקובץ תמליל JSONL של המפגש |
+
+### סוגי אירוע
+
+| אירוע | מתי זה מופעל | תוכן `toolInput` |
+|-------|--------------|----------------------|
+| `PreToolUse` | לפני Claude מפעיל כלי | קלט הכלי (למ"ג `{ command: "..." }` עבור Bash) |
+| `PostToolUse` | אחרי שכלי משלים | קלט הכלי + `tool_result` (הפלט) |
+| `Notification` | כאשר Claude שולח הודעה | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks חייבים תמיד להחזיר `allow()`, הם לא יכולים לחסום הודעות |
+| `Stop` | כאשר מפגש Claude מסתיים | ריק |
+
+---
+
+## סדר הערכה
+
+מדיניות מוערכת בסדר זה:
+
+1. מדיניות מובנית (בסדר הגדרה)
+2. מדיניות מותאמת אישית מפורשת מ-`customPoliciesPath` (בסדר `.add()`)
+3. מדיניות כללי כתיבה מפרויקט `.failproofai/policies/` (קבצים אלפביתיים, סדר `.add()` בתוך)
+4. מדיניות כללי כתיבה ממשתמש `~/.failproofai/policies/` (קבצים אלפביתיים, סדר `.add()` בתוך)
+
+<Note>
+ה-`deny` הראשון מקצר את כל המדיניות הלאה. כל הודעות `instruct` מצטברות ומסופקות ביחד.
+</Note>
+
+---
+
+## ייבוא חוזר
+
+קבצי מדיניות מותאמת אישית יכולים לייבא מודולים מקומיים באמצעות נתיבים יחסיים:
+
+```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");
+  },
+});
+```
+
+כל הייבוא היחסי הנגיש מקובץ הכניסה מוגדר מחדש. זה מיושם על ידי כתיבת מחדש של `from "failproofai"` יבוא לנתיב dist בפועל וּיצירת קבצי `.mjs` זמניים להבטחת תאימות ESM.
+
+---
+
+## סינון סוגי אירוע
+
+השתמש ב-`match.events` כדי להגביל מתי מדיניות מופעלת:
+
+```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();
+  },
+});
+```
+
+השמט את `match` לחלוטין כדי להפעיל את כל סוגי האירוע.
+
+---
+
+## טיפול בשגיאות ומצבי כשל
+
+מדיניות מותאמת אישית היא **fail-open**: שגיאות אף פעם לא חוסמות מדיניות מובנית או קורסות מטפל hook.
+
+| כשל | התנהגות |
+|---------|----------|
+| `customPoliciesPath` לא הוגדרה | אין מדיניות מותאמת אישית מפורשת פועלת; מדיניות כללי כתיבה ומובנית ממשיכות בדרך כלל |
+| קובץ לא נמצא | אזהרה נרשמת ל-`~/.failproofai/hook.log`; מובנית ממשיכה |
+| שגיאת תחביר/ייבוא (מפורשת) | שגיאה נרשמת ל-`~/.failproofai/hook.log`; מדיניות מותאמת אישית מפורשת דילגה |
+| שגיאת תחביר/ייבוא (כללי כתיבה) | שגיאה נרשמת; הקובץ הזה דילג, קבצי כללי כתיבה אחרים עדיין טוענים |
+| `fn` זורק בזמן ריצה | שגיאה נרשמת; hook ההוא טרוט כ-`allow`; hoooks אחרים ממשיכים |
+| `fn` לוקח יותר מ-10 שניות | timeout רשום; טיפול כ-`allow` |
+| ספריית כללי כתיבה חסרה | אין מדיניות כללי כתיבה פועלת; אין שגיאה |
+
+<Tip>
+כדי לנפות באגים בשגיאות מדיניות מותאמת אישית, צפה בקובץ היומן:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## דוגמה מלאה: מדיניות מרובה
+
+```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 };
+```
+
+---
+
+## דוגמאות
+
+ספריית `examples/` מכילה קבצי מדיניות מוכנים לריצה:
+
+| קובץ | תוכן |
+|------|----------|
+| `examples/policies-basic.js` | חמש מדיניות התחלה המכסות מצבי כשל רגילים של agent |
+| `examples/policies-advanced/index.js` | דפוסים מתקדמים: ייבוא חוזר, קריאות async, שריטה פלט, ו-hooks של סוף מפגש |
+| `examples/convention-policies/security-policies.mjs` | מדיניות אבטחה מבוססת כללי כתיבה (חסום כתיבות .env, מנע כתיבה מחדש של היסטוריית git) |
+| `examples/convention-policies/workflow-policies.mjs` | מדיניות זרימה עבודה מבוססת כללי כתיבה (תזכוּרי בדיקה, קבצי כתיבה של ביקורת) |
+
+### שימוש בדוגמאות קובץ מפורשות
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### שימוש בדוגמאות מבוססות כללי כתיבה
+
+```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/
+```
+
+אין צורך בפקודת התקנה — הקבצים נאספים באופן אוטומטי בקריאת hook הבאה.