> ## 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.

# מדיניות מותאמות

> כתוב, בדוק והפעל מדיניות JavaScript או TypeScript למקרי כשל ספציפיים לסוכנים שלך.

מדיניות מותאמות הופכות דפוס כשל מהעקיבות או הביקורות שלך להחלטה שפועלת בזמן שסוכן עובד. מדיניות יכולה לאשר פעולה, לתת הנחיה לסוכן, או לכל הפחות לדחות את הפעולה לפני שהיא גורמת לתקادם נוסף.

השתמש במדיניות מותאמת כאשר ההתנהגות תלויה בכלים שלך, בנתיבים, בפקודות, בסביבות או בכללי התפעול. בדוק את [קטלוג המדיניות המובנה](/he/policies/builtin-catalog) תחילה כדי שלא תיצור מחדש בקרה קיימת.

## כתוב מדיניות מותאמת

<Tabs>
  <Tab title="Dashboard">
    1. עבור ל **Admin → policy editor**, בחר **New policy** והתאר את הכשל שאתה רוצה למנוע.
    2. הוסף את קוד המדיניות, ואז בדוק התאמות צפויות וא-התאמות בטוחות בעורך. פתור כל שגיאת אימות.
    3. שמור את הטיוטה ובחר **Publish version** כדי ליצור גרסה בלתי ניתנת לשינוי.
    4. עבור ל **Admin → enforcement**, פרוס את הגרסה על מכונת בדיקה במצב **observe**, ואימת את ההחלטות שלה תחת **Observe → policy** לפני שאתה אוכפה אותה.

           <img src="https://mintcdn.com/exosphere/WgPwQzedeDNwJBTy/images/dashboard/policy-editor.png?fit=max&auto=format&n=WgPwQzedeDNwJBTy&q=85&s=7c01c862f4ec601d0535a6969eb619ce" alt="עורך המדיניות המשמש לכתיבה והפרסום של מדיניות מותאמת." width="2938" height="1608" data-path="images/dashboard/policy-editor.png" />
  </Tab>

  <Tab title="CLI">
    1. צור `.failproofai/policies/checkout-policies.ts`. שם הקובץ חייב להסתיים ב `policies.js`, `policies.mjs` או `policies.ts`.
    2. רשום מדיניות אחת או יותר עם `customPolicies.add()`.
    3. אמת והתקן את הקובץ עם `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`.
    4. הפעל פעולה אחת תואמת ופעולה בטוחה אחת. הרץ `failproofai policies`, ואז בדוק את ההחלטות המיוחסות תחת **Observe → policy**.
  </Tab>
</Tabs>

## התחל עם כלל צר

מדיניות זו חוסמת פקודות Kubernetes הרסניות רק כאשר הפקודה מכוונת לייצור. הכל מחוץ לדפוס כשל זה בדיוק מחזיר `allow()`.

```ts theme={null}
import { customPolicies, allow, deny } from "failproofai";

const DESTRUCTIVE_KUBECTL = /\bkubectl\s+(delete|replace)\b/i;
const PRODUCTION_TARGET = /(?:--context|--namespace|-n)\s+(prod|production)\b/i;

customPolicies.add({
  name: "block-destructive-production-kubectl",
  description: "Block destructive Kubernetes commands against production",
  match: { events: ["PreToolUse"] },
  fn: async ({ toolName, toolInput }) => {
    if (toolName !== "Bash") return allow();

    const command = String(toolInput?.command ?? "");
    if (!DESTRUCTIVE_KUBECTL.test(command)) return allow();
    if (!PRODUCTION_TARGET.test(command)) return allow();

    return deny(
      "Destructive production Kubernetes commands require the approved deployment workflow.",
    );
  },
});
```

מדיניות טובות מספיק צרות כדי להסביר במשפט אחד. התאם את הפעולה הנצפית — לא הכוונה שאתה מקווה שהסוכן היה בעל — וחזור `allow()` ברגע שהכלל אינו חל.

## בחר החלטה

| עוזר               | תוצאה                                          | השתמש בו כאשר                                                    |
| ------------------ | ---------------------------------------------- | ---------------------------------------------------------------- |
| `allow(reason?)`   | הפעולה ממשיכה.                                 | המדיניות אינה חלה או הפעולה בטוחה.                               |
| `instruct(reason)` | הפעולה ממשיכה עם הנחיה כאשר ההשקה תומכת בה.    | אתה רוצה להנחות את הסוכן לכיוון גישה טובה יותר מבלי לכפות משתנה. |
| `deny(reason)`     | הפעולה חסומה כאשר האירוע וההשקה תומכים בחסימה. | הפעולה חייבת שלא להמשיך.                                         |

כתוב את הסיבה לסוכן שחייב להתאושש. הסבר מה התגלה ומה הוא אמור לעשות במקום זאת.

<Warning>
  אל תשתמש ב `instruct()` לגבול בטיחות. מסירת הנחיות משתנה בהתאם להשקת הסוכן. השתמש ב `deny()` כאשר יש למנוע את הפעולה.
</Warning>

## אובייקט מדיניות

```ts theme={null}
customPolicies.add({
  name: "policy-name",
  description: "What this policy prevents",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => allow(),
});
```

| שדה            | נדרש | תיאור                                                                        |
| -------------- | ---- | ---------------------------------------------------------------------------- |
| `name`         | כן   | מזהה יציב עבור המדיניות. שמור על שמות ייחודיים בקבצים.                       |
| `description`  | לא   | מטרה קריאה לאדם המוצגת בקצרי מדיניות והחלטות.                                |
| `match.events` | לא   | סוגי אירועים המפעילים את המדיניות. השמטת `match` מפעילה אותה לכל אירוע זמין. |
| `fn`           | כן   | פונקציה סינכרונית או אסינכרונית החוזרת על `allow`, `instruct` או `deny`.     |

סנן כלים בתוך `fn`. `match.toolNames` אינו חלק מסוג המדיניות המותאמת הציבורי.

## הקשר מדיניות

כל מדיניות מקבלת `PolicyContext`.

| שדה         | סוג                                    | מה הוא מכיל                                                                   |
| ----------- | -------------------------------------- | ----------------------------------------------------------------------------- |
| `eventType` | `HookEventType`                        | אירוע מנורמל המוערך כרגע.                                                     |
| `toolName`  | `string \| undefined`                  | שם כלי קנוני כמו `Bash`, `Read`, `Write` או `Edit`.                           |
| `toolInput` | `Record<string, unknown> \| undefined` | קלט קנוני לקריאת הכלי הנוכחית.                                                |
| `payload`   | `Record<string, unknown>`              | כל עומס אירוע מנורמל.                                                         |
| `session`   | `SessionMetadata \| undefined`         | ID הסשן, תיקיית עבודה, נתיב תמלול, מצב הרשאה ומטא-נתונים של השקה כאשר זמינים. |
| `cli`       | `string \| undefined`                  | סוכן משדר בן ההשקה, כגון `claude`, `codex` או `cursor`.                       |
| `params`    | `Record<string, unknown>`              | פרמטרים של מדיניות מובנית. מדיניות מותאמות מקבלות כרגע אובייקט ריק.           |

התייחס לכל ערך אופציונלי כבר-אופציונלי באמת. גרסאות סוכן וסוגי אירועים אינם מספקים את אותם שדות.

### קלטים כלים נפוצים

Failproof AI מנרמל כלים נפוצים בהשקות נתמכות כך שמדיניות יכולה בדרך כלל להשתמש בצורת קלט אחת.

| כלי     | שדות נפוצים                             |
| ------- | --------------------------------------- |
| `Bash`  | `command`                               |
| `Read`  | `file_path`                             |
| `Write` | `file_path`, `content`                  |
| `Edit`  | `file_path`, `old_string`, `new_string` |
| `Grep`  | `pattern`, `path`                       |

השתמש בהסכמה הגנה משום שערכי קלט כלים מוקלדים כ `unknown`:

```ts theme={null}
const command = String(ctx.toolInput?.command ?? "");
const filePath = String(ctx.toolInput?.file_path ?? "");
```

## בחר את האירוע

| אירוע                         | מתי הוא פועל             | שימוש טיפוסי                                                                          |
| ----------------------------- | ------------------------ | ------------------------------------------------------------------------------------- |
| `PreToolUse`                  | לפני שכלי מבוצע.         | חסום או הנחה פקודות, כתיבות, קריאות ופעולות חיצוניות.                                 |
| `PostToolUse`                 | לאחר שכלי חוזר.          | בדוק תוצאות לפני שהן מגיעות לסוכן. דחייה חוסמת את כל התוצאה; זה לא מעביר שדות נבחרים. |
| `PermissionRequest`           | כאשר הסוכן מבקש הרשאה.   | יישם כללי הרשאה ספציפיים ארגוניים.                                                    |
| `UserPromptSubmit`            | לפני שהנושא שהוגש ממשיך. | דחה הנחיות אסורות או הוסף הנחיית זרימת עבודה.                                         |
| `Stop`                        | כאשר הסוכן מנסה לסיים.   | דרוש תנאי השלמה מגיע, כגון שלב אימות מקומי.                                           |
| `SubagentStop`                | כאשר תת-סוכן מנסה לסיים. | סגור עבודה משונה לפני שהיא חוזרת להורה.                                               |
| `SessionStart` / `SessionEnd` | בגבולות הסשן.            | הקלט או בדוק מצב ברמת הסשן.                                                           |

זמינות אירועים והתנהגות חסימה תלויים בהשקת סוכן. ראה [סוכן harnesses](/he/reference/harnesses) לפני שאתה מסתמך על אירוע בקfleet מעורב.

<Accordion title="כל שמות אירוע מדיניות">
  `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch` ו `Setup`.
</Accordion>

## כתוב דפוסי מדיניות נפוצים

### חסום כתיבות לנתיבים מוגנים

```ts theme={null}
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "block-generated-file-edits",
  description: "Require generated files to be changed through their generator",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();

    const filePath = String(ctx.toolInput?.file_path ?? "");
    if (!/(^|\/)(dist|generated)\//.test(filePath)) return allow();

    return deny("Edit the source and run the generator instead of changing generated output.");
  },
});
```

### תן הנחיה שאינה חוסמת

```ts theme={null}
import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "prefer-reviewed-deploy-command",
  description: "Guide agents toward the reviewed deployment wrapper",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();

    const command = String(ctx.toolInput?.command ?? "");
    if (!/^kubectl\s+apply\b/.test(command.trim())) return allow();

    return instruct("Use ./scripts/deploy-reviewed instead of invoking kubectl directly.");
  },
});
```

### סגור השלמת סשן

```ts theme={null}
import { execFileSync } from "node:child_process";
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "require-clean-typecheck",
  description: "Require the project typecheck to pass before the agent finishes",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    const cwd = ctx.session?.cwd;
    if (!cwd) return allow();

    try {
      execFileSync("bunx", ["tsc", "--noEmit"], {
        cwd,
        stdio: "ignore",
        timeout: 8_000,
      });
      return allow();
    } catch {
      return deny("Fix the typecheck errors before finishing the task.");
    }
  },
});
```

<Warning>
  אירוע `Stop` מדחה יכול לגרום לסוכן להתנסות מחדש. סגור רק בתנאי שהסוכן יכול להשביח בסביבה הנוכחית, וקשור כל קריאת תהליך משנה או רשת.
</Warning>

## קובצי מדיניות טעינה

### קובצי קונבנציה

קובצי קונבנציה נטענים באופן אוטומטי:

```text theme={null}
<project>/.failproofai/policies/security-policies.ts
~/.failproofai/policies/personal-policies.mjs
```

* ספריות מדיניות פרויקט ומשתמש נטענות שתיהן.
* קובצים נטענים בסדר אלפביתי בתוך כל ספרייה.
* קובץ חייב להסתיים ב `policies.js`, `policies.mjs` או `policies.ts`.
* קריאות `customPolicies.add()` מרובות בקובץ אחד נתמכות.
* ייבואים יחסיים מודולים מקומיים נתמכים.
* מדיניות פרויקט יכולה להיות מחויבת כך שאותם כללים עוקבים את המילון.

### קובצים מפורשים

השתמש בנתיבים מפורשים כאשר אימות או תצורה צריכה לשם ישירות את קובץ הכניסה:

```bash theme={null}
failproofai policies --install \
  --custom ./security.policies.ts \
  --custom ./workflow.policies.ts \
  --scope project
```

קובצים מפורשים נטענים ראשון, ואחריו קובצי קונבנציה פרויקט ואחריו קובצי קונבנציה משתמש. קובץ שהתגלה דרך שתי הנתיבים נטען פעם אחת.

## אימות וביקורת

אימות מבצע את המודול דרך מנקה הייצור ומאשר שהוא רושם לפחות מדיניות אחת.

```bash theme={null}
failproofai policies --install \
  --custom ./.failproofai/policies/checkout-policies.ts \
  --scope project
failproofai policies
```

אימות תופס קבצים חסרים, שגיאות תחביר, ייבואים לא פתורים, חריגות ברמה העליונה וזמן פתיחת מודול. זה לא מוכיח שההיגיון התאמה שלך נכון.

בדוק לפחות במקרים אלה:

* פעולה אחת שחייבת להתאים והפיק את סיבת המדיניות המיועדת.
* פעולה קרובה אך בטוחה שחייבת להחזיר `allow()`.
* שדות כלים חסרים או מעוותים.
* תחביר פקודות, נתיבים, ציטוטים, טבעות והוא לבן חלופי.
* תהליך משנה או תלות רשת לא זמינה.

יחס את התוצאה למדיניות המותאמת שלך תחת **Observe → policy**. בדיקה חסומה אינה מספיקה אם מדיניות מובנית שונה קיבלה את ההחלטה.

## התנהגות ריצה

* מדיניות מובנית מוערכת לפני מדיניות מותאמת.
* ה `deny` ראשון מפסיק הערכה מדיניות נוספת.
* תוצאות `instruct` מרובות יכולות להיות משולבות כאשר אין מדיניות מכפה את האירוע.
* לפונקציה מדיניות יש פקדונון הרצה של 10 שניות.
* יוצא חריג או פגיעה מתעד וטוען כ `allow()`.
* קובץ קונבנציה שלא נטעונה משודך; קבצים מותאמים וחוקים מובנים אחרים ממשיכים.
* טעינת מודול ברמה העליונה יש גם לפקדונון 10 שניות.
* מצב התבוננות ענן מפעיל את המדיניות אך מקליט החלטה שאינה כל משדר ללא הטלה.

שמור על מודולי מדיניות דטרמיניסטיים ומהיר. תרחק מקריאות רשת ברמה עליונה או התחלת שרת. עבודה כבולה בתוך `fn`, תופס כשלי תלות, ובחר במודע אם כך כשל צריך לאשר או לכפות את הפעולה.

## ייצוא API

| ייצוא                        | מטרה                                        |
| ---------------------------- | ------------------------------------------- |
| `customPolicies.add(policy)` | רשום מדיניות מותאמת כאשר המודול נטעונה.     |
| `allow(reason?)`             | אשר את הפעולה.                              |
| `instruct(reason)`           | אשר את הפעולה ותן הנחיה כאשר נתמך.          |
| `deny(reason)`               | חסום את הפעולה כאשר נתמך.                   |
| `getCustomHooks()`           | החזר את המדיניות כרגע הרשומה בשדורי המודול. |
| `clearCustomHooks()`         | בטל את השדורי זה, בעיקר לבדיקות ו loaders.  |

TypeScript מייצא `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` ו `PolicyFunction`.

<Card title="פרוס מדיניות מותאמות" icon="server-cog" href="/he/policies/deploy">
  פרסם גרסה, פרוס אותה במצב התבוננות, אימת החלטות, ועבור לאכיפה.
</Card>