Architecture

title: Архитектура description: “Как работают обработчик хука, загрузка конфигурации и оценка политик” icon: sitemap

Этот документ объясняет, как failproofai работает внутри: как система хуков перехватывает вызовы инструментов агента, как загружается и объединяется конфигурация, как оцениваются политики и как панель мониторинга отслеживает активность агента.

Обзор

failproofai состоит из двух независимых подсистем:

Обработчик хука — быстрый CLI подпроцесс, который Claude Code вызывает при каждом вызове инструмента агента. Оценивает политики и возвращает решение.
Agent Monitor (Dashboard) — веб-приложение Next.js для мониторинга сеансов агента и управления политиками.

Обе подсистемы используют общие файлы конфигурации в ~/.failproofai/ и директории .failproofai/ проекта, но запускаются как отдельные процессы и взаимодействуют только через файловую систему.

Обработчик хука

Интеграция с Claude Code

Когда вы запускаете failproofai policies --install, она записывает записи вроде этой в ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "failproofai --hook PreToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [ ... ]
  }
}

Затем Claude Code вызывает failproofai --hook PreToolUse как подпроцесс перед каждым вызовом инструмента, передавая JSON-полезную нагрузку на stdin.

Формат полезной нагрузки

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
  "cwd": "/home/user/myproject",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "sudo apt install nodejs" }
}

Для событий PostToolUse полезная нагрузка также содержит tool_result с выводом инструмента. Обработчик устанавливает лимит stdin в 1 МБ. Полезные нагрузки, превышающие это значение, отбрасываются и все политики неявно разрешают.

Формат ответа

Deny (PreToolUse):

{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
  }
}

Deny (PostToolUse):

{
  "hookSpecificOutput": {
    "additionalContext": "Blocked by failproofai because: API key detected in output"
  }
}

Instruct (любое событие кроме Stop):

{
  "hookSpecificOutput": {
    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
  }
}

Событие Stop instruct:

Код выхода: 2
Причина записана в stderr (не stdout)

Allow:

Код выхода: 0
Пустой stdout

Allow с сообщением: allow(message) позволяет политике отправить информационный контекст обратно Claude, даже когда операция разрешена. Обработчик хука записывает следующий JSON в stdout (не в файл конфигурации — это ответ обработчика Claude Code, как и ответы deny и instruct выше):

// Записано в stdout процессом обработчика хука
{
  "hookSpecificOutput": {
    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
  }
}

Код выхода: 0 (операция разрешена)
Когда несколько политик возвращают allow с сообщением, их сообщения объединяются с переводами строк в одну строку additionalContext
Если ни одна политика не предоставляет сообщение, stdout пустой (как раньше)

Конвейер обработки

src/hooks/handler.ts реализует полный конвейер:

stdin JSON
  → парсинг полезной нагрузки (макс 1 МБ)
  → извлечение метаданных сеанса (session_id, cwd, tool_name, tool_input, и т. д.)
  → readMergedHooksConfig(cwd)    ← объединяет конфигурацию проекта + локальную + глобальную
  → регистрация включенных встроенных политик с разрешенными параметрами
  → загрузка пользовательских политик из customPoliciesPath (если установлено)
  → регистрация пользовательских политик в реестре политик
  → оценка всех политик (встроенные первыми, затем пользовательские)
      → первый deny вызывает короткое замыкание
      → решения instruct накапливаются
      → сообщения allow накапливаются
  → запись решения JSON в stdout
  → сохранение события в ~/.failproofai/hook-activity.jsonl
  → выход

Весь процесс выполняется менее чем за 100 мс для типичных полезных нагрузок без вызовов LLM.

Загрузка конфигурации

src/hooks/hooks-config.ts реализует загрузку конфигурации с тремя областями.

[1] {cwd}/.failproofai/policies-config.json        ← проект  (наивысший приоритет)
[2] {cwd}/.failproofai/policies-config.local.json  ← локальная
[3] ~/.failproofai/policies-config.json             ← глобальная   (наименьший приоритет)

Логика объединения:

enabledPolicies — дедуплицированное объединение всех трех файлов
policyParams — по ключу политики, первый файл, который его определяет, побеждает полностью
customPoliciesPath — первый файл, который его определяет, побеждает
llm — первый файл, который его определяет, побеждает

Веб-панель использует readHooksConfig() (только глобальная) для чтения и записи, так как она не вызывается с cwd проекта.

Оценка политик

src/hooks/policy-evaluator.ts запускает политики по порядку. Для каждой политики:

Ищет схему params политики (если она есть).
Читает policyParams[policy.name] из объединенной конфигурации.
Объединяет предоставленные пользователем значения над значениями по умолчанию схемы для создания ctx.params.
Вызывает policy.fn(ctx) с разрешенным контекстом.
Если результат deny, останавливается немедленно и возвращает это решение.
Если результат instruct, накапливает сообщение и продолжает.
Если результат allow, продолжает к следующей политике.

После выполнения всех политик:

Если был возвращен какой-либо deny, выдает ответ deny.
Если были собраны возвращаемые instruct, выдает один ответ instruct со всеми сообщениями объединены.
В противном случае выдает ответ allow (пустой stdout, выход 0).

Встроенные политики

src/hooks/builtin-policies.ts определяет все 39 встроенных политик как объекты BuiltinPolicyDefinition:

interface BuiltinPolicyDefinition {
  name: string;
  description: string;
  fn: (ctx: PolicyContext) => PolicyResult;
  match: {
    events: HookEventType[];
    tools?: string[];
  };
  defaultEnabled: boolean;
  category: string;
  beta?: boolean;
  params?: PolicyParamsSchema;
}

Политики, которые принимают params, объявляют PolicyParamsSchema с типами и значениями по умолчанию для каждого параметра. Оценщик политик внедряет разрешенные значения в ctx.params перед вызовом fn. Функции политик читают ctx.params без защиты от нулевых значений, потому что значения по умолчанию всегда применяются сначала. Сопоставление паттернов внутри политик использует проанализированные токены команды (argv), а не сопоставление по сырой строке. Это предотвращает обход с помощью инъекции оператора оболочки (например, паттерн для sudo systemctl status * не может быть обойден добавлением ; rm -rf / к команде).

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

src/hooks/custom-hooks-registry.ts реализует реестр, основанный на globalThis:

const REGISTRY_KEY = "__failproofai_custom_hooks__";

export const customPolicies = {
  add(hook: CustomHook): void { ... }
};

export function getCustomHooks(): CustomHook[] { ... }
export function clearCustomHooks(): void { ... }  // используется в тестах

src/hooks/custom-hooks-loader.ts загружает файл политики пользователя:

Читает customPoliciesPath из конфигурации; пропускает, если отсутствует.
Разрешает абсолютный путь; проверяет, существует ли файл.
Переписывает все импорты from "failproofai" на фактический путь dist, чтобы customPolicies разрешился на один и тот же реестр globalThis.
Рекурсивно переписывает переходящие локальные импорты для обеспечения совместимости ESM.
Записывает временные файлы .mjs и import() файл записи.
Вызывает getCustomHooks() для получения зарегистрированных хуков.
Очищает все временные файлы в блоке finally.

При любой ошибке (файл не найден, синтаксическая ошибка, ошибка импорта) ошибка регистрируется в ~/.failproofai/hook.log и загрузчик возвращает пустой массив. Встроенные политики не затрагиваются. Пользовательские политики оцениваются после всех встроенных политик. deny пользовательской политики все еще вызывает короткое замыкание для дальнейших пользовательских политик (но все встроенные уже выполнены к этому моменту).

Логирование активности

После каждого события хука обработчик добавляет строку JSONL в ~/.failproofai/hook-activity.jsonl:

{
  "timestamp": "2026-04-06T12:34:56.789Z",
  "sessionId": "abc123",
  "eventType": "PreToolUse",
  "toolName": "Bash",
  "policyName": "block-sudo",
  "decision": "deny",
  "reason": "sudo command blocked by failproofai",
  "durationMs": 12
}

По одной строке на политику, которая приняла решение, отличное от allow. Решения allow не регистрируются (чтобы сохранить размер файла маленьким).

Архитектура панели

Панель является приложением Next.js 16 с использованием App Router с React Server Components и Server Actions.

app/
  layout.tsx                  ← Корневой макет (тема, телеметрия, навигация)
  projects/page.tsx           ← Server component: список всех проектов Claude
  project/[name]/page.tsx     ← Server component: список сеансов в проекте
  project/[name]/session/
    [sessionId]/page.tsx      ← Server component: отображение просмотра сеанса
  policies/page.tsx           ← Client component: управление политиками + журнал активности
  actions/
    get-hooks-config.ts       ← Чтение конфигурации + список политик
    update-hooks-config.ts    ← Включение/отключение политики
    update-policy-params.ts   ← Обновление параметров политики
    get-hook-activity.ts      ← Постраничный поиск журнала активности
    install-hooks-web.ts      ← Установка/удаление хуков из браузера
  api/
    download/[project]/[session]/route.ts   ← Экспорт сеанса по CLI (JSONL или JSON)

Поток данных:

Компоненты страниц вызывают lib/projects.ts и lib/log-entries.ts для чтения данных проекта/сеанса непосредственно из файловой системы (нет уровня API для чтения).
Страница Policies использует Server Actions для всех изменений (переключение, обновление параметров, установка/удаление).
Просмотрщик сеанса парсит формат стенограммы JSONL Claude и отображает хронологию сообщений и вызовов инструментов.

Ключевые дизайн-решения:

Нет базы данных — все постоянное состояние находится в обычных файлах (~/.failproofai/, ~/.claude/projects/).
Server Actions для изменений — REST API не требуется для операций CRUD.
React Server Components для страниц чтения — более быстрая начальная загрузка, нет клиентского пакета для выборки данных.
Клиентские компоненты только там, где требуется интерактивность (переключатели политик, поиск активности, просмотр журнала).

Структура файлов

failproofai/
├── bin/
│   └── failproofai.mjs           # Маршрутизатор CLI (hook / dashboard / install / и т. д.)
├── src/hooks/
│   ├── handler.ts                # Конвейер события хука
│   ├── builtin-policies.ts       # 39 определений политик
│   ├── policy-evaluator.ts       # Механизм выполнения политик
│   ├── policy-registry.ts        # Регистрация и поиск политик
│   ├── policy-types.ts           # Интерфейсы TypeScript
│   ├── hooks-config.ts           # Загрузка конфигурации с несколькими областями
│   ├── custom-hooks-registry.ts  # Реестр хуков, основанный на globalThis
│   ├── custom-hooks-loader.ts    # Загрузчик ESM для пользовательских JS хуков
│   ├── manager.ts                # Операции установки / удаления / списка
│   ├── install-prompt.ts         # Интерактивное приглашение выбора политики
│   ├── hook-logger.ts            # Логирование в hook.log
│   ├── hook-activity-store.ts    # Сохранение активности в hook-activity.jsonl
│   └── llm-client.ts             # Клиент LLM API (для политик с поддержкой AI)
├── app/                          # Next.js панель (страницы + server actions)
├── lib/                          # Общие утилиты
│   ├── projects.ts               # Перечисление проектов Claude из файловой системы
│   ├── log-entries.ts            # Парсинг формата стенограммы Claude JSONL
│   ├── paths.ts                  # Разрешение путей системы
│   └── ...
├── components/                   # Общие компоненты React UI
├── contexts/                     # Поставщики контекста React (тема, авто-обновление, телеметрия)
├── examples/                     # Примеры файлов пользовательского хука
└── __tests__/                    # Модульные и E2E тесты

Начало работы

Основные концепции

CLI

Инструменты

Продвинутый

Примеры

title: Архитектура description: “Как работают обработчик хука, загрузка конфигурации и оценка политик” icon: sitemap

Обзор

Обработчик хука

Интеграция с Claude Code

Формат полезной нагрузки

Формат ответа

Конвейер обработки

Загрузка конфигурации

Оценка политик

Встроенные политики

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

Логирование активности

Архитектура панели

Структура файлов

​title: Архитектура description: “Как работают обработчик хука, загрузка конфигурации и оценка политик” icon: sitemap

​Обзор

​Обработчик хука

​Интеграция с Claude Code

​Формат полезной нагрузки

​Формат ответа

​Конвейер обработки

​Загрузка конфигурации

​Оценка политик

​Встроенные политики

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

​Логирование активности

​Архитектура панели

​Структура файлов

title: Архитектура description: “Как работают обработчик хука, загрузка конфигурации и оценка политик” icon: sitemap

Обзор

Обработчик хука

Интеграция с Claude Code

Формат полезной нагрузки

Формат ответа

Конвейер обработки

Загрузка конфигурации

Оценка политик

Встроенные политики

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

Логирование активности

Архитектура панели

Структура файлов