Несколько агентов в одних блокнотах

Claude Code, opencode и другие пишут в одни и те же блокноты

Типичная схема: Claude Code пишет заметки, opencode читает и дополняет, внешний harness (external-harness) только читает, человек проверяет и утверждает.

Токен на каждого агента #

uv run okf-notebooks token create --actor claude-code      --label laptop
uv run okf-notebooks token create --actor opencode         --label workstation
uv run okf-notebooks token create --actor external-harness --label ci-reader
uv run okf-notebooks token list
uv run okf-notebooks token revoke t-1a2b3c4d

Токен показывается один раз, на диске хранится SHA-256. Актор и права определяются только токеном: агент не может назвать себя другим актором. Метка (--label) пишется в историю, поэтому заводите отдельный токен на каждую машину или клиента.

Актора human токена не имеет: его действия доступны только через CLI и веб-интерфейс ревью.

Права #

По умолчанию:

Права переопределяются в конфиге (допустимо read, write, notebook_creation, comments):

actors:
  claude-code:
    allow: [read, write, notebook_creation, comments]
    notebook_creation: direct    # этому агенту можно создавать блокноты сразу
  opencode:
    allow: [read, write]
  external-harness:
    allow: [read]

Без allow актор получает comments вместе с остальными правами по умолчанию; явный allow без comments отключает комментарии для актора (см. «Комментарии» в docs/review-ui.md). verify и archive выдать агенту нельзя. Политику создания можно задать общую (notebook_creation.default) и переопределить для актора. off в YAML пишется как off; сервер понимает и «голое» off, которое YAML читает как false.

Что видят агенты #

• Все агенты с read видят активные блокноты и заметки.
• Чужие заявки (proposed) другим агентам не показываются; даже при поиске похожего блокнота виден только статус, но не содержимое.
• Метка авторства generated.by (<актор>/<версия клиента>) ставится сервером; агент её не редактирует. Версия клиента берётся из initialize MCP-запроса.

Параллельная запись и конфликты #

Запись идёт под файловыми блокировками с атомарной заменой файла, каждая запись — отдельный git-коммит с актором и меткой в сообщении (если git.commit_per_write: true).

• notebook_write создаёт новую заметку; имя уникализируется, затереть чужую заметку нельзя.
• notebook_update с body или fields требует base_etag — etag, полученный при notebook_read. Если заметку успели изменить, придёт ошибка conflict с актуальной версией: агент перечитывает, объединяет изменения и повторяет.
• notebook_update с append не требует etag: дописывание в конец безопасно при параллельной работе.

Практика для двух агентов над одной заметкой: логи и накопление фактов — через append, переписывание текста — через read → update с base_etag.

Лимиты и защита #

• Лимит запросов на токен: server.rate_limit_per_token (120/min, также N/sec, N/hour).
• Лимит размера тела: server.max_body_bytes.
• Не более 3 одновременных заявок от одного актора (блокнотов и типов).
• limits.max_notebooks, limits.max_concept_bytes, limits.max_search_results ограничивают рост базы.
• Текст заметок агенту отдаётся в маркерах с одноразовым nonce, чтобы содержимое не воспринималось как инструкция.
• В заметки нельзя записать то, что похоже на секреты (токены, ключи): запись отклоняется правилом secret.

Как разделить зоны ответственности #

1. На один блокнот — один scope: агенты выбирают блокнот по нему, а не по имени.
2. В AGENTS.md / CLAUDE.md каждого проекта вставьте блок из okf-notebooks print-agent-guide.
3. Рецензирует человек: после проверки заметка получает verified (см. заметки и проверка). Любая правка агентом снимает отметку, так что «проверено» всегда относится к текущему тексту.