> ## 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: На основе соглашений (рекомендуется)

Поместите файлы `*policies.{js,mjs,ts}` в `.failproofai/policies/` — они загружаются автоматически, никаких флагов или изменений конфигурации не требуется. Это работает как 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;                         // 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)`     | Заблокировать операцию             | Агент не должен выполнять это действие                          |
| `instruct(message)` | Добавить контекст без блокировки   | Дайте агенту дополнительный контекст для сохранения направления |

`deny(message)` — сообщение отображается Claude с префиксом `"Blocked by failproofai:"`. Единственное `deny` прекращает все дальнейшие оценки.

`instruct(message)` — сообщение добавляется в контекст Claude для текущего вызова инструмента. Все сообщения `instruct` накапливаются и доставляются вместе.

<Tip>
  Вы можете добавить дополнительное руководство к любому сообщению `deny` или `instruct`, добавив поле `hint` в `policyParams` — без изменения кода. Это работает для пользовательских (`custom/`), проектных соглашений (`.failproofai-project/`) и пользовательских соглашений (`.failproofai-user/`) политик. См. [Конфигурация → hint](/ru/configuration#hint-cross-cutting) для получения информации.
</Tip>

### Информационные сообщения allow

`allow(message)` разрешает операцию **и** отправляет информационное сообщение обратно Claude. Сообщение доставляется как `additionalContext` в ответе stdout обработчика перехвата — тот же механизм, используемый `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.");

    // ... 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" \| ... }` — перехваты всегда должны возвращать `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");
  },
});
```

Все относительные импорты, доступные из файла записи, разрешены. Это реализуется путём переписывания импортов `from "failproofai"` на фактический путь dist и создания временных файлов `.mjs` для обеспечения совместимости ESM.

***

## Фильтрация типов событий

Используйте `match.events` для ограничения срабатывания политики:

```js theme={null}
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` полностью, чтобы срабатывать для каждого типа события.

***

## Обработка ошибок и режимы отказа

Пользовательские политики являются **отказоустойчивыми**: ошибки никогда не блокируют встроенные политики и не сбивают обработчик перехвата.

| Отказ                                  | Поведение                                                                                             |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `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";

// 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`                         | Пять начальных политик, охватывающих распространённые режимы отказа агента                                           |
| `examples/policies-advanced/index.js`                | Продвинутые паттерны: переходящие импорты, асинхронные вызовы, очистка выходных данных и перехваты завершения сессии |
| `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}
# 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/
```

Команда установки не требуется — файлы автоматически подбираются при следующем событии перехвата.