> ## 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 में अपने नियम लिखें - सम्मेलनों को लागू करें, ड्रिफ्ट को रोकें, विफलताओं का पता लगाएं, बाहरी सिस्टम के साथ इंटीग्रेट करें

कस्टम पॉलिसीज आपको किसी भी एजेंट व्यवहार के लिए नियम लिखने देती हैं: प्रोजेक्ट सम्मेलनों को लागू करें, ड्रिफ्ट को रोकें, विनाशकारी संचालन को गेट करें, फंसे हुए एजेंटों का पता लगाएं, या Slack, अनुमोदन वर्कफ़्लो और बहुत कुछ के साथ इंटीग्रेट करें। ये बिल्ट-इन पॉलिसीज के समान हुक ईवेंट सिस्टम और `allow`, `deny`, `instruct` निर्णयों का उपयोग करते हैं।

***

## त्वरित उदाहरण

```js theme={null}
// 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 theme={null}
failproofai policies --install --custom ./my-policies.js
```

***

## कस्टम पॉलिसीज लोड करने के दो तरीके

### विकल्प 1: सम्मेलन-आधारित (अनुशंसित)

`.failproofai/policies/` में `*policies.{js,mjs,ts}` फाइलें डालें और वे स्वचालित रूप से लोड हो जाती हैं — कोई फ्लैग या कॉन्फ़िग परिवर्तन की आवश्यकता नहीं। यह git हुक्स की तरह काम करता है: एक फाइल डालें, यह बस काम करता है।

```
# प्रोजेक्ट स्तर — git में कमिट किया गया, टीम के साथ साझा किया गया
.failproofai/policies/security-policies.mjs
.failproofai/policies/workflow-policies.mjs

# यूजर स्तर — व्यक्तिगत, सभी प्रोजेक्ट्स पर लागू होता है
~/.failproofai/policies/my-policies.mjs
```

**यह कैसे काम करता है:**

* दोनों प्रोजेक्ट और यूजर डायरेक्ट्रीज को स्कैन किया जाता है (यूनियन — पहली-स्कोप-जीत नहीं)
* फाइलें प्रत्येक डायरेक्ट्री में वर्णानुक्रम में लोड होती हैं। ऑर्डर को नियंत्रित करने के लिए `01-`, `02-` के साथ प्रीफिक्स करें
* केवल `*policies.{js,mjs,ts}` से मेल खाने वाली फाइलें लोड होती हैं; अन्य फाइलें अनदेखी की जाती हैं
* प्रत्येक फाइल स्वतंत्र रूप से लोड होती है (फाइल प्रति फेल-ओपन)
* स्पष्ट `--custom` और बिल्ट-इन पॉलिसीज के साथ काम करता है

<Tip>
  सम्मेलन पॉलिसीज आपके संगठन के लिए गुणवत्ता मानक बनाने का सबसे आसान तरीका है। `.failproofai/policies/` को git में कमिट करें और प्रत्येक टीम सदस्य को स्वचालित रूप से समान नियम मिलते हैं — कोई प्रति-डेवलपर सेटअप आवश्यक नहीं है। जब आपकी टीम नई विफलता मोड की खोज करे, एक पॉलिसी जोड़ें और पुश करें। समय के साथ ये एक जीवंत गुणवत्ता मानक बन जाता है जो हर योगदान के साथ बेहतर होता रहता है।
</Tip>

### विकल्प 2: स्पष्ट फाइल पाथ

```bash theme={null}
# कस्टम पॉलिसीज फाइल के साथ इंस्टॉल करें
failproofai policies --install --custom ./my-policies.js

# पॉलिसीज फाइल पाथ बदलें
failproofai policies --install --custom ./new-policies.js

# कॉन्फ़िग से कस्टम पॉलिसीज पाथ हटाएं
failproofai policies --uninstall --custom
```

समाधान किया गया निरपेक्ष पाथ `policies-config.json` में `customPoliciesPath` के रूप में संग्रहीत होता है। फाइल हर हुक ईवेंट पर ताजा लोड होती है - ईवेंट्स के बीच कोई कैशिंग नहीं होती है।

### दोनों को एक साथ उपयोग करना

सम्मेलन पॉलिसीज और स्पष्ट `--custom` फाइल सह-अस्तित्व में रह सकते हैं। लोड क्रम:

1. स्पष्ट `customPoliciesPath` फाइल (यदि कॉन्फ़िगर की गई हो)
2. प्रोजेक्ट सम्मेलन फाइलें (`{cwd}/.failproofai/policies/`, वर्णानुक्रम)
3. यूजर सम्मेलन फाइलें (`~/.failproofai/policies/`, वर्णानुक्रम)

***

## API

### आयात

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

### `customPolicies.add(hook)`

एक पॉलिसी को रजिस्टर करता है। एक ही फाइल में कई पॉलिसीज के लिए जितनी बार चाहें इसे कॉल करें।

```ts theme={null}
customPolicies.add({
  name: string;                         // आवश्यक - अद्वितीय पहचानकर्ता
  description?: string;                 // `failproofai policies` आउटपुट में दिखाया गया
  match?: { events?: HookEventType[] }; // ईवेंट प्रकार द्वारा फ़िल्टर करें; सभी से मेल खाने के लिए छोड़ दें
  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
});
```

### निर्णय सहायक

| फंक्शन              | प्रभाव                          | कब उपयोग करें                                     |
| ------------------- | ------------------------------- | ------------------------------------------------- |
| `allow()`           | संचालन को मौन रूप से अनुमति दें | क्रिया सुरक्षित है, कोई संदेश आवश्यक नहीं         |
| `deny(message)`     | संचालन को ब्लॉक करें            | एजेंट को यह क्रिया नहीं लेनी चाहिए                |
| `instruct(message)` | ब्लॉक किए बिना संदर्भ जोड़ें    | एजेंट को ट्रैक पर रहने के लिए अतिरिक्त संदर्भ दें |

`deny(message)` - संदेश Claude को `"Blocked by failproofai:"` प्रीफिक्स के साथ प्रकट होता है। एक एकल `deny` सभी आगे के मूल्यांकन को शॉर्ट-सर्किट करता है।

`instruct(message)` - संदेश वर्तमान टूल कॉल के लिए Claude के संदर्भ में जोड़ा जाता है। सभी `instruct` संदेश जमा किए जाते हैं और एक साथ दिए जाते हैं।

<Tip>
  आप `policyParams` में एक `hint` फील्ड जोड़कर किसी भी `deny` या `instruct` संदेश को अतिरिक्त मार्गदर्शन जोड़ सकते हैं — कोई कोड परिवर्तन आवश्यक नहीं है। यह कस्टम (`custom/`), प्रोजेक्ट सम्मेलन (`.failproofai-project/`), और यूजर सम्मेलन (`.failproofai-user/`) पॉलिसीज के लिए भी काम करता है। विवरण के लिए [कॉन्फ़िगरेशन → hint](/hi/configuration#hint-cross-cutting) देखें।
</Tip>

### सूचनात्मक allow संदेश

`allow(message)` संचालन की अनुमति देता है **और** Claude को एक सूचनात्मक संदेश वापस भेजता है। संदेश हुक हैंडलर के stdout प्रतिक्रिया में `additionalContext` के रूप में दिया जाता है — `instruct` द्वारा उपयोग की जाने वाली समान तंत्र, लेकिन शब्दार्थ में भिन्न: यह एक चेतावनी नहीं, बल्कि एक स्थिति अपडेट है।

| फंक्शन           | प्रभाव                               | कब उपयोग करें                                                        |
| ---------------- | ------------------------------------ | -------------------------------------------------------------------- |
| `allow(message)` | अनुमति दें और Claude को संदर्भ भेजें | एक जांच पास होने की पुष्टि करें, या समझाएं कि एक जांच क्यों छोड़ी गई |

उपयोग के मामले:

* **स्थिति पुष्टिकरण:** `allow("All CI checks passed.")` — Claude को बताता है कि सब कुछ हरा है
* **फेल-ओपन स्पष्टीकरण:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude को बताता है कि एक जांच क्यों छोड़ी गई ताकि इसे पूरा संदर्भ हो
* **कई संदेश जमा होते हैं:** यदि कई पॉलिसीज प्रत्येक `allow(message)` लौटाती हैं, सभी संदेश नई लाइनों के साथ जुड़ते हैं और एक साथ दिए जाते हैं

```js theme={null}
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.");

    // ... शाखा स्थिति की जांच करें ...
    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 से पहले एक टूल चलाता है   | टूल का इनपुट (जैसे Bash के लिए `{ command: "..." }`)                                                                                                       |
| `PostToolUse`  | एक टूल पूरा होने के बाद          | टूल का इनपुट + `tool_result` (आउटपुट)                                                                                                                      |
| `Notification` | जब Claude एक नोटिफिकेशन भेजता है | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - हुक्स को हमेशा `allow()` लौटाना चाहिए, वे नोटिफिकेशन को ब्लॉक नहीं कर सकते |
| `Stop`         | जब Claude सेशन समाप्त होता है    | खाली                                                                                                                                                       |

***

## मूल्यांकन क्रम

पॉलिसीज को इस क्रम में मूल्यांकन किया जाता है:

1. बिल्ट-इन पॉलिसीज (परिभाषा क्रम में)
2. `customPoliciesPath` से स्पष्ट कस्टम पॉलिसीज (`.add()` क्रम में)
3. प्रोजेक्ट `.failproofai/policies/` से सम्मेलन पॉलिसीज (फाइलें वर्णानुक्रम में, `.add()` क्रम में)
4. यूजर `~/.failproofai/policies/` से सम्मेलन पॉलिसीज (फाइलें वर्णानुक्रम में, `.add()` क्रम में)

<Note>
  पहला `deny` सभी बाद की पॉलिसीज को शॉर्ट-सर्किट करता है। सभी `instruct` संदेश जमा किए जाते हैं और एक साथ दिए जाते हैं।
</Note>

***

## ट्रांजिटिव आयात

कस्टम पॉलिसी फाइलें सापेक्ष पाथों का उपयोग करके स्थानीय मॉड्यूल को आयात कर सकती हैं:

```js theme={null}
// 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");
  },
});
```

प्रविष्टि फाइल से पहुंचने योग्य सभी सापेक्ष आयात समाधान किए जाते हैं। यह `failproofai` आयातों को वास्तविक dist पाथ में फिर से लिखकर और ESM संगतता सुनिश्चित करने के लिए अस्थायी `.mjs` फाइलें बनाकर लागू किया जाता है।

***

## ईवेंट प्रकार फ़िल्टरिंग

यह सीमित करने के लिए `match.events` का उपयोग करें कि पॉलिसी कब फायर होती है:

```js theme={null}
customPolicies.add({
  name: "require-summary-on-stop",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    // केवल तब फायर होता है जब सेशन समाप्त होता है
    // ctx.session.transcriptPath में पूर्ण सेशन लॉग होता है
    return allow();
  },
});
```

सभी ईवेंट प्रकारों पर फायर करने के लिए `match` को पूरी तरह छोड़ दें।

***

## त्रुटि हैंडलिंग और विफलता मोड

कस्टम पॉलिसीज **फेल-ओपन** हैं: त्रुटियां कभी भी बिल्ट-इन पॉलिसीज को ब्लॉक नहीं करती या हुक हैंडलर को क्रैश नहीं करती हैं।

| विफलता                            | व्यवहार                                                                                      |
| --------------------------------- | -------------------------------------------------------------------------------------------- |
| `customPoliciesPath` सेट नहीं है  | कोई स्पष्ट कस्टम पॉलिसीज नहीं चलती; सम्मेलन पॉलिसीज और बिल्ट-इन सामान्य रूप से जारी रहते हैं |
| फाइल नहीं मिली                    | चेतावनी `~/.failproofai/hook.log` में लॉग की जाती है; बिल्ट-इन जारी रहते हैं                 |
| सिंटैक्स/आयात त्रुटि (स्पष्ट)     | त्रुटि `~/.failproofai/hook.log` में लॉग की जाती है; स्पष्ट कस्टम पॉलिसीज छोड़ दी जाती हैं   |
| सिंटैक्स/आयात त्रुटि (सम्मेलन)    | त्रुटि लॉग की जाती है; वह फाइल छोड़ दी जाती है, अन्य सम्मेलन फाइलें अभी भी लोड होती हैं      |
| `fn` रनटाइम पर थ्रो करता है       | त्रुटि लॉग की जाती है; वह हुक `allow` के रूप में माना जाता है; अन्य हुक्स जारी रहते हैं      |
| `fn` 10 सेकंड से अधिक समय लेता है | समय समाप्त लॉग किया जाता है; `allow` के रूप में माना जाता है                                 |
| सम्मेलन डायरेक्ट्री गायब है       | कोई सम्मेलन पॉलिसीज नहीं चलती; कोई त्रुटि नहीं                                               |

<Tip>
  कस्टम पॉलिसी त्रुटियों को डीबग करने के लिए, लॉग फाइल को देखें:

  ```bash theme={null}
  tail -f ~/.failproofai/hook.log
  ```
</Tip>

***

## पूर्ण उदाहरण: कई पॉलिसीज

```js theme={null}
// my-policies.js
import { customPolicies, allow, deny, instruct } from "failproofai";

// एजेंट को secrets/ डायरेक्ट्री में लिखने से रोकें
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();
  },
});

// एजेंट को ट्रैक पर रखें: कमिट करने से पहले टेस्ट सत्यापित करें
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();
  },
});

// फ्रीज अवधि के दौरान अनियोजित निर्भरता परिवर्तनों को रोकें
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`                         | पांच स्टार्टर पॉलिसीज जो सामान्य एजेंट विफलता मोड्स को कवर करती हैं                     |
| `examples/policies-advanced/index.js`                | उन्नत पैटर्न: ट्रांजिटिव आयात, async कॉल्स, आउटपुट स्क्रबिंग, और सेशन-एंड हुक्स         |
| `examples/convention-policies/security-policies.mjs` | सम्मेलन-आधारित सुरक्षा पॉलिसीज (.env लेखन को ब्लॉक करें, git इतिहास पुनर्लेखन को रोकें) |
| `examples/convention-policies/workflow-policies.mjs` | सम्मेलन-आधारित वर्कफ़्लो पॉलिसीज (टेस्ट रिमाइंडर, ऑडिट फाइल लेखन)                       |

### स्पष्ट फाइल उदाहरणों का उपयोग

```bash theme={null}
failproofai policies --install --custom ./examples/policies-basic.js
```

### सम्मेलन-आधारित उदाहरणों का उपयोग

```bash theme={null}
# प्रोजेक्ट स्तर पर कॉपी करें
mkdir -p .failproofai/policies
cp examples/convention-policies/*.mjs .failproofai/policies/

# या यूजर स्तर पर कॉपी करें
mkdir -p ~/.failproofai/policies
cp examples/convention-policies/*.mjs ~/.failproofai/policies/
```

कोई इंस्टॉल कमांड आवश्यक नहीं है — फाइलें अगले हुक ईवेंट पर स्वचालित रूप से उठाई जाती हैं।