Документация settings.json

Область применения. Этот документ описывает файл подключения хуков (settings.json) адаптера Claude Code. Другие harness используют собственные нативные поверхности настроек — см. site/content/docs/harnesses/<harness>.mdx для эквивалентной точки входа конфигурации каждого адаптера.

Обзор

settings.json настраивает выполнение хуков Claude Code для экосистемы Apothem. Он объявляет, какие хуки срабатывают на какие события, их тайм-ауты и поверхность разрешений верхнего уровня. Apothem поставляет один канонический шаблон, потому что Claude Code загружает ~/.claude/settings.json на всех поддерживаемых платформах.

Среда выполнения только для Python

Каждый настроенный хук использует exec-форму команды Claude Code. Поставляемый шаблон несёт токен ${HARNESS_ROOT}:

{
  "type": "command",
  "command": "python",
  "args": ["${HARNESS_ROOT}/apothem/hooks/dispatch.py", "PreToolUse", "pretooluse-write"]
}

apothem install отрисовывает токен в абсолютный путь корня harness (форма с прямым слешем, действительная в Windows, macOS и Linux), так что установленный settings.json напрямую вызывает диспетчер, материализованный в ~/.claude/.apothem/support/hooks/dispatch.py. Диспетчер и гейт соответствия (~/.claude/.apothem/support/conformity/gate.py, с его schema-фикстурами рядом в ~/.claude/.apothem/support/schemas/) — это самостоятельные скрипты стандартной библиотеки — на хосте не требуется импортируемый пакет apothem, и один шаблон обслуживает каждую платформу.

Схема конфигурации хуков

Разрешения

"permissions": {
  "allow": ["Read", "Glob", "Grep"]
}

Инструменты, отсутствующие в allow, требуют явного одобрения для каждого вызова или разрешения на уровне рабочего пространства. Инструменты только для чтения предварительно одобрены; операции записи (Write, Edit, NotebookEdit, Bash) проходят через валидатор PreToolUse.

События хуков

Значения тайм-аутов отражают канонические бюджеты событий хуков — таблица ниже воспроизводит их для удобства читателя; канонический источник имеет приоритет.

dispatch.py дополнительно принимает UserPromptSubmit и Notification в своём белом списке событий. Ни одно не подключено в поставляемых шаблонах; добавьте блок matcher с тем же шаблоном локатора + диспетчеризации, чтобы включить его.

Поля верхнего уровня

Валидация

Три валидатора покрывают поверхность хуков с возрастающей строгостью:

# Структурный + гигиена Python (быстро, офлайн)
python scripts/dev/validate_hooks.py

# Полная экосистема (структура + frontmatter + делегированные проверки хуков)
python scripts/dev/validate_ecosystem.py

# Состязательный обход (штурмует каждую настроенную команду хука деградированными входами)
python scripts/dev/chaos_pass.py

Все три должны завершиться с кодом 0 перед коммитом изменений хуков или настроек.

Разовый дымовой тест одного события:

python src/apothem/hooks/dispatch.py --event-name SessionStart

Ожидаемый вывод: однострочный JSON-конверт, содержащий hookSpecificOutput.

Частые проблемы

SessionStart истекает по тайм-ауту

Чаще всего локатор find-python обнаруживает заглушку Microsoft Store и не может разрешить настоящий интерпретатор. Проверьте:

python src/apothem/hooks/dispatch.py --event-name SessionStart

Если команда печатает действительный JSON-конверт, но панель Claude Code показывает тайм-аут, повысьте timeout события в settings.json. Если команда падает на уровне оболочки, установите настоящий CPython 3.10+ и убедитесь, что он находится в PATH или обнаруживается локатором.

Каждый Write/Edit блокируется

PreToolUse помечает внутренние термины плана в содержимом, записываемом вне корня установки harness (~/.claude/ для адаптера Claude Code). Просмотрите содержимое на предмет нарушений CM-7 (см. src/apothem/rules/persistent-conventions-vigilance.md). Только доменный язык для артефактов кодовой базы.

settings.json не загружается

Claude Code читает ~/.claude/settings.json. Убедитесь, что Apothem установлен в ожидаемый корень harness, и перезапустите сессию после изменения файла.

Хуки молча ничего не делают

Контракт хука — «всегда завершаться с 0, всегда выдавать действительный JSON». Если интерпретатор не может быть найден, локатор возвращает пустоту, и команда становится no-op. Запустите chaos_pass.py, чтобы подтвердить, что каждый настроенный хук возвращает действительный конверт — он ловит деградированные пути разрешения, которые скрыла бы живая сессия.

Слоистая приоритетность

Claude Code разрешает эффективный объект настроек, компонуя три слоя в возрастающем порядке приоритета:

Значения более высокого уровня переопределяют значения более низкого уровня на уровне листового ключа — когда и слой проекта, и слой локально-для-пользователя объявляют запись permissions.allow, берётся объединение; когда оба объявляют скаляр вроде theme, побеждает значение локально-для-пользователя. Точная семантика слияния по ключам принадлежит harness Claude Code.

Создание локального переопределения пользователя

1. Скопируйте settings.local.example.json (корень репозитория) в <harness-root>/settings.local.json. Имя файла settings.local.json соответствует шаблону .gitignore, поэтому файл никогда не попадает в систему контроля версий.
2. Отредактируйте локальную копию — оставьте только ключи для переопределения; harness компонует слои, поэтому отсутствующие ключи наследуются из слоя проекта.
3. Перед сохранением убедитесь, что файл разбирается как действительный JSON — harness отклоняет некорректный JSON при старте сессии.