Хуки и принуждение Claude Code (PEP)

Подключение Claude Code связывает половину наблюдения — входящая OTLP-телеметрия, исходящие рёбра доступа. Эта страница — управляющая половина: хуки Claude Code сообщают коннектору о решениях по инструментам, а опциональная точка принуждения политик (PEP) превращает этот канал в шлюз — коннектор отвечает на совпавший хук PreToolUse / PermissionRequest решением permissionDecision, равным deny или ask, и фиксирует каждый шлюз как finding.

По умолчанию поведение намеренно сначала-чтение: при отсутствии настроенной политики принуждения хуки наблюдаются, но не пропускаются через шлюз. Принуждение — это именованный, явный opt-in, и невалидная политика падает при запуске — коннектор не будет молча работать без управления.

Как работает канал хуков

Приёмник OTLP/HTTP коннектора (по умолчанию loopback 127.0.0.1:4318) также обслуживает конечную точку хуков по адресу hook_path (по умолчанию /hooks). На машине разработчика конфигурация хуков Claude Code отправляет свои события хуков на эту loopback-конечную точку — точный синтаксис настроек хуков относится к собственной документации Claude Code; то, чем владеет этот продукт, — это приёмник и политика ниже.

События хуков и OTLP-телеметрия об одном и том же вызове инструмента коррелируются (correlation_window, по умолчанию 5s, удерживает одну сторону в ожидании другой), поэтому пропущенное через шлюз действие и его телеметрия оседают как одна связная история, а не две разрозненные записи. Сессия, которая продолжает посылать хуки, но замолкает в OTLP дольше silence_threshold (по умолчанию 2m), помечается как пробел в телеметрии — сигнал противодействия уклонению.

Включение принуждения

Добавьте политику enforcement в конфигурацию источника (OLIVARES_SOURCES_CONFIG):

{
  "sources": [{
    "name": "claude",
    "kind": "claude",
    "tenant": "<tenant-id>",
    "config": {
      "enforcement": "{\"rules\":[{\"tool\":\"Bash\",\"decision\":\"ask\",\"reason\":\"shell needs a human\"},{\"resource_kind\":\"file\",\"mode\":\"write\",\"decision\":\"deny\"}]}"
    }
  }]
}

Правила сопоставляются по имени инструмента и/или виду ресурса и режиму доступа; решение — это deny или ask (эскалация человеку в сессии). Совпавшие хуки PreToolUse / PermissionRequest получают это решение обратно как permissionDecision Claude Code; всё остальное проходит наблюдаемым. Каждый шлюз фиксируется как finding, поэтому след принуждения можно запросить, а не восстанавливать по слухам.

Аварийный выключатель главнее всего

Если estate (или конкретный агент) находится под аварийной остановкой, claude.tool.use убивается на уровне управления независимо от этой политики — шлюз остановки проверяется раньше любого правила по инструментам и срабатывает с отказом (fails closed).

Состояние флота: управляемые настройки, под наблюдением

Принуждение на хуке — это один слой. Слой уровня всего флота — это файл управляемых настроек Claude Code, который источник managed-settings наблюдает в режиме только-чтение:

{
  "sources": [{
    "name": "fleet-policy",
    "kind": "managed-settings",
    "tenant": "<tenant-id>",
    "config": {
      "config_path": "/etc/claude-code/managed-settings.json",
      "expected_policy": "{…governance-authored intent…}"
    }
  }]
}

Ключ	По умолчанию	Значение
config_path	/etc/claude-code/managed-settings.json (Linux)	действующий файл управляемых настроек хоста (macOS: /Library/Application Support/ClaudeCode/…)
scope	имя хоста ОС	область атрибуции (id хоста / имя дистрибутива)
expected_policy	—	опциональное заявленное намерение; если задано, коннектор сообщает о дрейфе (разрешённая политика vs наблюдаемая конфигурация). Пусто = только наблюдение

Связанные опциональные наблюдатели на источнике claude: managed_mcp_path (моделирует порядок вычисления списка разрешённых managed-MCP и помечает записи allow только по имени) и sandbox_path (findings о состоянии настроек изоляции песочницы) — оба только-чтение, оба выключены, пока не указаны на файл.

Что вы увидите в консоли

Claude Code governance — это поверхность авторинга и петли истины: политика, которую вы намереваетесь применить, конфигурация, которую хосты несут на самом деле, и дрейф между ними. Шлюзы и findings о пробелах в телеметрии оседают в Security; сама сессия остаётся видимой в Sessions:

Честные ограничения

• PEP пропускает через шлюз то, о чём сообщают хуки. Хост, чьи хуки не настроены, не проходит через шлюз — сочетайте флот с наблюдателем управляемых настроек, чтобы отсутствие было видно, и с ядерным резервом, чтобы он не был слепым.
• ask откладывает решение человеку в сессии — это трение, а не замок. deny — это замок.
• Подпроцессы здесь вне области охвата (хуки срабатывают на собственные вызовы инструментов Claude Code); см. страницу enterprise OTel о том, до чего телеметрическое окружение дотягивается, а до чего нет.

Связанное

• Подключение Claude Code — половина наблюдения.
• Enterprise OTel для Claude Code — телеметрия флота, метки, трассировка.
• Управление и одобрение — модель авторизации, в которую подключается PEP.