Пользовательские политики

Пользовательские политики преобразуют паттерн сбоя из ваших трасс или аудитов в решение, которое выполняется во время работы агента. Политика может разрешить действие, дать агенту рекомендацию или запретить действие до того, как оно вызовет еще один инцидент. Используйте пользовательскую политику, когда поведение зависит от ваших инструментов, путей, команд, окружений или операционных правил. Сначала проверьте пакет политик Failproof AI, чтобы не воссоздавать существующий контроль.

Разработка пользовательской политики

Dashboard
CLI

Перейдите в Admin → policy editor, выберите New policy и опишите сбой, который вы хотите предотвратить.
Добавьте исходный код политики, затем протестируйте ожидаемые совпадения и безопасные несовпадения в редакторе. Исправьте все ошибки валидации.
Сохраните черновик и выберите Publish version, чтобы создать неизменяемую версию.
Перейдите в Admin → enforcement, развертните версию на тестовой машине в режиме observe и проверьте её решения в Observe → policy перед её применением.

Создайте .failproofai/policies/checkout-policies.ts. Имя файла должно заканчиваться на policies.js, policies.mjs или policies.ts.
Зарегистрируйте одну или несколько политик с помощью customPolicies.add().
Валидируйте и установите файл с помощью failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project.
Запустите одно совпадающее действие и одно безопасное действие. Выполните failproofai policies, затем проверьте приписанные решения в Observe → policy.

Начните с узкого правила

Эта политика блокирует деструктивные команды Kubernetes только когда команда нацелена на production. Все остальное вне этого точного паттерна сбоя возвращает allow().

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)`	Операция продолжается с рекомендацией где поддерживается harness.	Вы хотите направить агента к лучшему подходу без применения инварианта.
`deny(reason)`	Операция блокируется когда событие и harness поддерживают блокировку.	Действие не должно продолжаться.

Напишите причину для агента, который должен восстановиться. Объясните, что было обнаружено и что он должен делать вместо этого.

Не используйте instruct() для границы безопасности. Доставка рекомендаций варьируется в зависимости от harness агента. Используйте deny() когда действие должно быть предотвращено.

Объект политики

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 не является частью публичного типа custom-policy.

Контекст политики

Каждая политика получает PolicyContext.

Поле	Тип	Что оно содержит
`eventType`	`HookEventType`	Нормализованное событие, которое в данный момент оценивается.
`toolName`	`string \| undefined`	Канонический имя инструмента, такое как `Bash`, `Read`, `Write` или `Edit`.
`toolInput`	`Record<string, unknown> \| undefined`	Канонический ввод для текущего вызова инструмента.
`payload`	`Record<string, unknown>`	Полный нормализованный payload события.
`session`	`SessionMetadata \| undefined`	ID сессии, рабочая директория, путь транскрипта, режим разрешений и метаданные harness, когда доступны.
`cli`	`string \| undefined`	Исходный harness агента, такой как `claude`, `codex` или `cursor`.
`params`	`Record<string, unknown>`	Встроенные параметры политики. Пользовательские политики в настоящее время получают пустой объект.

Рассматривайте каждое необязательное значение как действительно необязательное. Версии агентов и типы событий не предоставляют одинаковые поля.

Общие входы инструментов

Failproof AI нормализует общие инструменты в поддерживаемых harnesses, поэтому политика обычно может использовать одну форму ввода.

Инструмент	Общие поля
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

Используйте оборонительное приведение типов, потому что значения входа инструмента типизированы как unknown:

const command = String(ctx.toolInput?.command ?? "");
const filePath = String(ctx.toolInput?.file_path ?? "");

Выберите событие

Событие	Когда оно выполняется	Типичное использование
`PreToolUse`	Перед выполнением инструмента.	Блокируйте или направляйте команды, записи, чтения и внешние действия.
`PostToolUse`	После возврата инструмента.	Проверьте результаты перед тем, как они достигнут агента. Отказ блокирует весь результат; он не редактирует выбранные поля.
`PermissionRequest`	Когда агент запрашивает разрешение.	Применяйте правила разрешений, специфичные для организации.
`UserPromptSubmit`	Перед продолжением отправленной подсказки.	Отклоняйте запрещённые инструкции или добавляйте рекомендации по рабочему процессу.
`Stop`	Когда агент пытается завершить.	Требуйте достижимое условие завершения, такое как локальный шаг проверки.
`SubagentStop`	Когда субагент пытается завершить.	Контролируйте делегированную работу перед её возвратом к родительскому процессу.
`SessionStart` / `SessionEnd`	На границах сессии.	Запишите или проверьте состояние на уровне сессии.

Доступность события и поведение блокировки зависят от harness агента. Смотрите Agent harnesses перед использованием события в смешанном парке.

Все имена событий политики

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.

Разработка общих паттернов политик

Блокируйте записи в защищённые пути

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.");
  },
});

Дайте неблокирующие рекомендации

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.");
  },
});

Контролируйте завершение сессии

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.");
    }
  },
});

Отказанное событие Stop может заставить агента повторить попытку. Контролируйте только условие, которое агент может удовлетворить в текущей среде, и ограничивайте каждый подпроцесс или сетевой вызов.

Загрузка файлов политик

Файлы соглашений

Файлы соглашений загружаются автоматически:

<project>/.failproofai/policies/security-policies.ts
~/.failproofai/policies/personal-policies.mjs

Загружаются как проектные, так и пользовательские директории политик.
Файлы загружаются в алфавитном порядке в каждой директории.
Файл должен заканчиваться на policies.js, policies.mjs или policies.ts.
Поддерживаются множественные вызовы customPolicies.add() в одном файле.
Поддерживаются относительные импорты из локальных модулей.
Проектные политики могут быть закомиченты, так что одинаковые правила следуют репозиторию.

Явные файлы

Используйте явные пути когда валидация или конфигурация должны назвать файл входа напрямую:

failproofai policies --install \
  --custom ./security.policies.ts \
  --custom ./workflow.policies.ts \
  --scope project

Явные файлы загружаются первыми, затем следуют проектные файлы соглашений и пользовательские файлы соглашений. Файл, обнаруженный по обоим путям, загружается один раз.

Валидируйте и тестируйте

Валидация выполняет модуль через продакшн-загрузчик и подтверждает, что он регистрирует по крайней мере одну политику.

failproofai policies --install \
  --custom ./.failproofai/policies/checkout-policies.ts \
  --scope project
failproofai policies

Валидация ловит отсутствующие файлы, синтаксические ошибки, неразрешённые импорты, исключения верхнего уровня и таймауты загрузки модуля. Она не доказывает, что ваша логика совпадения правильна. Протестируйте по крайней мере эти случаи:

Одно действие, которое должно совпасть и произвести предполагаемую причину политики.
Одно близкое но безопасное действие, которое должно вернуть allow().
Отсутствующие или неправильно сформированные поля инструментов.
Альтернативный синтаксис команд, пути, кавычки, регистр и пробелы.
Недоступная зависимость подпроцесса или сети.

Приписывайте результат вашей пользовательской политике в Observe → policy. Заблокированный тест недостаточен, если другая встроенная политика приняла решение.

Поведение при выполнении

Встроенные политики оцениваются перед пользовательскими политиками.
Первый deny останавливает дальнейшую оценку политики.
Множественные результаты instruct могут быть объединены, когда ни одна политика не отклоняет событие.
Функция политики имеет дедлайн выполнения 10 секунд.
Выброшенное исключение или таймаут логируется и рассматривается как allow().
Файл соглашений, который не загружается, пропускается; другие пользовательские файлы и встроенные политики продолжаются.
Загрузка модуля верхнего уровня также имеет дедлайн 10 секунд.
Режим облачного наблюдения выполняет политику но записывает решение, не относящееся к allow, без применения его.

Держите модули политик детерминированными и быстрыми. Избегайте вызовов сети верхнего уровня или запуска сервера. Ограничивайте работу внутри fn, ловите сбои зависимостей и сознательно выбирайте должно ли это разрешение или отказ выполнить операцию.

Экспорты API

Экспорт	Цель
`customPolicies.add(policy)`	Зарегистрируйте пользовательскую политику при загрузке модуля.
`allow(reason?)`	Разрешите операцию.
`instruct(reason)`	Разрешите операцию и предоставьте рекомендацию где поддерживается.
`deny(reason)`	Заблокируйте операцию где поддерживается.
`getCustomHooks()`	Верните политики, которые в настоящее время зарегистрированы в реестре модулей.
`clearCustomHooks()`	Очистите этот реестр, в основном для тестов и загрузчиков.

TypeScript экспортирует PolicyContext, PolicyResult, CustomHook, PolicyDecision и PolicyFunction.

Разверните пользовательские политики

Опубликуйте версию, разверните её в режиме наблюдения, проверьте решения и переходите к применению.

Connect your agents

Reference

Пользовательские политики

Разработка пользовательской политики

Начните с узкого правила

Выберите решение

Объект политики

Контекст политики

Общие входы инструментов

Выберите событие

Разработка общих паттернов политик

Блокируйте записи в защищённые пути

Дайте неблокирующие рекомендации

Контролируйте завершение сессии

Загрузка файлов политик

Файлы соглашений

Явные файлы

Валидируйте и тестируйте

Поведение при выполнении

Экспорты API

Разверните пользовательские политики

​Разработка пользовательской политики

​Начните с узкого правила

​Выберите решение

​Объект политики

​Контекст политики

​Общие входы инструментов

​Выберите событие

​Разработка общих паттернов политик

​Блокируйте записи в защищённые пути

​Дайте неблокирующие рекомендации

​Контролируйте завершение сессии

​Загрузка файлов политик

​Файлы соглашений

​Явные файлы

​Валидируйте и тестируйте

​Поведение при выполнении

​Экспорты API

Разверните пользовательские политики

Разработка пользовательской политики

Начните с узкого правила

Выберите решение

Объект политики

Контекст политики

Общие входы инструментов

Выберите событие

Разработка общих паттернов политик

Блокируйте записи в защищённые пути

Дайте неблокирующие рекомендации

Контролируйте завершение сессии

Загрузка файлов политик

Файлы соглашений

Явные файлы

Валидируйте и тестируйте

Поведение при выполнении

Экспорты API