Skip to content

Защита в ядре: что возвращает dry_run у MCP и SDK, какие операции «выдают доступ», требовать ли человека при удалении — четыре решения #556

Open

Description

@bim-ba

О чём решение

«Показать, не отправляя» и вопрос перед опасным действием переезжают из CLI в ядро — это вы решили (#503 п. 3, #495 п. 15 и 16). E4 прислала план; первый PR (ядро, поведение CLI не меняется) уже можно писать. В четырёх местах нужен ваш выбор.

Слова: план запроса — то, что команда показывает при --dry-run: метод, адрес, параметры и тело, которые ушли бы; пометка для клиента — служебный признак инструмента MCP, по которому Claude Code спрашивает человека даже в режиме «не спрашивать».

Вопрос 1. Что возвращает инструмент MCP при dry_run=true

Обычно пишущий инструмент возвращает ответ сервиса. При dry_run ответа нет — есть план.

А. Тот же инструмент, результат — «ответ или план» Б. Отдельный инструмент plan(tool, arguments)
Пример tracker_issues_update(issue_id="DE-7", body={…}, dry_run=true) → {"dry_run": true, "request": {"method": "PATCH", "url": "…", "body": {…}}} plan(tool="tracker_issues_update", arguments={…}) → тот же объект
Зеркало с CLI (--dry-run — флаг команды) да нет
Схема результата у 260 пишущих инструментов становится «ответ ИЛИ план» не меняется
Новых инструментов 0 1
Агент не может забыть, что получил план, а не ответ поле dry_run: true в ответе другой инструмент

Рекомендация: А — зеркало: флаг там же, где у команды.

Вопрос 2. Что делает SDK при dry_run

Метод SDK обещает типом вернуть, например, Issue. План в этот тип не ложится.

А. Исключение с планом Б. Отдельный способ спросить план
Пример try: tracker.with_options(dry_run=True).issues.update(…)
except RequestPlanned as planned: print(planned.plan)
plan = tracker.plan(lambda t: t.issues.update(…))
Тип метода остаётся честным да да
Привычно нет: исключение как обычный исход да
Нового в SDK один класс исключения метод plan и правило, что внутри лямбды

Рекомендация: Б. «Покажи, что отправил бы» — обычный вопрос, а не ошибка; ловить исключение ради результата — неловко и легко проглотить настоящую ошибку рядом. Внутри это то же самое (план поднимается из ядра), но наружу — значение. E4 рекомендует А как меньшее по коду; разница в удобстве пользователя SDK.

Вопрос 3. Какие операции «выдают доступ»

Про них CLI начнёт спрашивать, а Claude Code — требовать человека. Точно входят 11: выдача и изменение доступа к форме и к странице Вики, права очереди и сущности Трекера, привязки доступа к книге, коллекции и общему объекту DataLens, назначение лицензии.

Под вопросом:

Операция За Против
datalens embeds create / update — встраивание чарта во внешний сайт открывает данные наружу это не «кому-то дали роль»
datalens embeddingsecrets create — ключ для встраивания ключ даёт доступ тому, у кого он есть сам по себе ничего не открывает
forms surveys publish — форма начинает принимать ответы становится доступна всем по ссылке это штатное действие, спрашивать каждый раз — шум
отзыв доступа (forms access revoke, wiki access delete / clear) можно отрезать людей от работы они уже помечены как удаляющие и уже спрашивают

Рекомендация: к 11 добавить встраивание (embeds create / update) и ключ встраивания — оба открывают данные за пределы организации; publish и отзыв не добавлять.

Вопрос 4. Требовать ли человека и для 67 удаляющих инструментов

Пометка «нужен человек» заставляет Claude Code спросить даже тогда, когда пользователь включил режим без вопросов.

А. Только «выдаёт доступ» (13 инструментов) Б. И удаляющие (ещё 67)
Агент в режиме без вопросов может удалить сам да (пометка «удаляет» остаётся) нет
Автономная работа агента (уборка за собой, тестовые прогоны) работает останавливается на каждом удалении
Защита от удаления по ошибке обычная: клиент спрашивает, если пользователь не отключил вопросы жёсткая

Рекомендация: А. Пользователь, включивший режим без вопросов, сделал это осознанно; отнимать его для 67 инструментов — значит сделать ycli непригодным для автономных агентов. Выдача доступа — другое: её последствия не видны и не возвращаются удалением.

Что решила сама (скажите, если не так)

  • dry_run у 260 пишущих инструментов появляется из одного места (слой сервера), а не правкой 260 подписей.
  • Команды выдачи доступа начнут спрашивать подтверждение — это ломает скрипты, которые звали их без --yes; выпускается как ломающее изменение с примером «было / стало».
  • Отказ подтвердить в SDK — отдельная ошибка «отклонено вызывающим», ничего не отправлено.
  • Многошаговая загрузка (wiki attachments upload) при dry_run показывает первый запрос, который что-то меняет, и останавливается — как сейчас в CLI.
  • Настройки на один вызов в SDK (with_options, принятая идея 28) делаются здесь же целиком: таймаут, повторы, dry_run.

Что бы я добавила сверху

  • План запроса при dry_run показывает секреты закрытыми и одинаково на трёх поверхностях — одна функция печати плана (сейчас маскирование живёт в CLI).
  • ycli … --dry-run -o json и план инструмента — один и тот же объект: агент может взять план из инструмента и показать человеку командой.

Что нужно от вас

«1 — А / Б, 2 — А / Б, 3 — 11 / 13 / свой состав, 4 — А / Б».

Activity

  1. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    1 - А
    2 - блин, ну как-будто бы да фича с Планом мне нравится больше чем какой-то небольшой самопис, но тогда придется и в SDK и в CLI и в MCP поддерживать эту фичу получается? что думаешь? мы же в вопросе 1 отказались от инструмента План, а тут мы его делаем?
    3 - согласен с твоей рекомендацией, только я надеюсь мы как-то такие операции будем определять просто с помощью метаданных и все? но я пока предлагаю покрыть что-то типа "обязательных" операций вот этой фичой, типа базовые вещи вот прям которые обязательно, потом если что масштабируем если UI/UX/DX будет нормальный
    4 - не, давай как я сказал пока на базовых штуках просто остановимся

  2. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    Решено (владелец, 2026-10-08): 1 — А, 3 — 13 (11 + встраивание embeds create / update + ключ встраивания), 4 — А. Вопрос 2 — ниже, нужно одно слово.

    К вопросу 3: да, только метаданными

    Признак «выдаёт доступ» — свойство операции рядом с её эффектом (так решено в #495, п. 15): одна пометка в endpoints.py, из неё выводится всё — вопрос в CLI, пометка «нужен человек» у инструмента, строка в справке. Нигде нет списка имён; расширить состав потом — поставить пометку ещё на одну операцию.

    К вопросу 2: это не три реализации одной фичи

    Механизм один и уже в ядре (#557): при dry_run ядро останавливает первую запись и поднимает RequestPlanned с планом. Каждая поверхность ловит его в одном своём месте и показывает по-своему:

    Поверхность Как просят Где ловится Строк
    CLI ycli tracker issues update DE-7 --summary x --dry-run обёртка команд (уже есть) 0 новых
    MCP tracker_issues_update(…, dry_run=true) → {"dry_run": true, "request": {…}} слой сервера, один раз на все 260 инструментов (вопрос 1, А) ~15
    SDK, вариант А tracker.with_options(dry_run=True).issues.update(…) → исключение RequestPlanned с планом ловит сам вызывающий 0 новых: это голый механизм ядра, он есть при любом ответе
    SDK, вариант Б tracker.plan(lambda t: t.issues.update(…)) → PlannedRequest метод plan, ловит за вызывающего ~10

    То есть Б — не третья реализация, а то же, что у CLI делает обёртка команд: поймать и отдать значением. А остаётся под ним в любом случае.

    Чем Б отличается от инструмента «план», от которого отказались в вопросе 1: там это был бы второй вход рядом с флагом у 260 инструментов; здесь — единственный удобный вход, потому что у метода SDK нет флага, в который ляжет план (тип возврата Issue, а не «Issue или план»).

    def plan(self, call: Callable[[Self], object]) -> PlannedRequest:
        """The first write ``call`` would send, not sent. Reads inside ``call`` go out."""
        try:
            call(self.with_options(dry_run=True))
        except RequestPlanned as planned:
            return planned.plan
        raise YandexInvalidRequestError("the call sends no write; there is nothing to plan")

    Рекомендация: Б — десять строк, и у пользователя SDK «покажи, что отправил бы» становится обычным вызовом, а не ловлей исключения. Если хотите сначала базовое — А уже есть бесплатно, plan добавится потом без поломки.

    Нужно от вас: «2 — А» или «2 — Б».

  3. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    да, вариант Б мне тоже больше нравится

  4. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor

    Решено (владелец, 2026-10-08): 2 — Б — у клиента SDK появляется метод plan(...), который возвращает запланированный запрос значением; голый механизм ядра (with_options(dry_run=True) и исключение RequestPlanned) остаётся под ним. Все четыре вопроса закрыты, метка снята. Исполнение — E4, после PR «выдаёт доступ» и dry_run в MCP.

  5. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor

    Исполнение «выдаёт доступ» (вопрос 3): список, форма и одно следствие, которое строже текста решения

    13 операций (14 функций в endpoints.py): forms access grant / update; wiki access create / update; tracker queues permissions-update; tracker entities permissions-update / permissions-update-direct; datalens workbooks / collections / sharedentries access-bindings-update; datalens licensing licenses-assign; datalens embeds create / update; datalens embeddingsecrets create. Не помечены, как решено: публикация формы, отзыв прав, wiki pages update с политикой доступа в теле.

    Форма: одно поле рядом с эффектом — grants_access=True в описании операции. Списка имён нигде нет; проверка ARCH-3 держит пометку инструмента честной в обе стороны.

    Поверхность Что происходит
    CLI команда спрашивает «это выдаёт доступ. Продолжить?»; --yes пропускает вопрос; без терминала и без --yes — отказ с кодом 2
    --dry-run как раньше: план, ничего не спрашивает
    MCP инструмент помечен _meta["anthropic/requiresUserInteraction"] = true
    SDK ничего по умолчанию; кто передал confirm, того спросят и про эти операции

    Что ломается: скрипт, который вызывал эти 14 команд без --yes и без терминала, начнёт получать код 2.

    Следствие для MCP, которое стоит знать

    Проверено по документации Claude Code (раздел «Require approval for a specific tool», прочитано 2026-10-10; нужен Claude Code 2.1.214 или новее):

    Режим клиента Что будет с помеченным инструментом
    обычный, acceptEdits, auto, bypassPermissions вопрос человеку на каждый вызов, без «больше не спрашивать»; правила разрешений его не снимают
    dontAsk вызов отклоняется
    без человека, с --permission-prompt-tool разрешение превращается в отказ
    приложение на Agent SDK вызов приходит в его canUseTool — приложение само показывает его человеку
    другие клиенты пометку не читают; о ней говорит только описание инструмента

    То есть агент без человека не сможет выдать доступ через эти 14 инструментов вообще — только командой CLI с --yes. Это строже, чем «спросить человека», но ровно тот случай, ради которого пометка сделана (пример в документации — именно выдача доступа).

    Исполняю так, с пометкой: считаю это тем, что решение и имело в виду. Если нужно иначе (например, оставить только слова в описании инструмента, без жёсткой пометки) — скажите, это одна константа.

    Мелкие развилки закрыла сама: пометка инструмента записана явно и проверяется; в описании инструмента — одна сгенерированная фраза для клиентов, которые пометку не читают; операции прав Трекера спрашивают и тогда, когда тело только отзывает права (пометка — свойство операции, а не тела).

  6. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor

    Ревью исполнения «выдаёт доступ» (#571): что подтверждено и два вопроса владельцу

    Подтверждено независимым ревью на голове PR: пометка стоит ровно на 14 функциях из 491, списка имён в коде нет; в протоколе у 14 инструментов лежит _meta["anthropic/requiresUserInteraction"] со значением JSON true; команда без терминала и без --yes отказывает во всех 20 тестовых случаях, никакая переменная окружения и yes | вопрос не снимают; --dry-run ничего не спрашивает и не отправляет.

    Найдена и чинится в том же PR дыра: в режиме ycli mcp start --tool-search помеченные инструменты уходили из списка, а общий инструмент-посредник запускал их без пометки — человека никто не спрашивал. Решение архитектора: в этом режиме 14 инструментов остаются в списке под своим именем и со своей пометкой, а посредник отказывается их запускать.

    Вопрос 1. Общая команда ycli api

    ycli api pages/7/access --service wiki -X POST -F role=editor отправляет выдачу доступа без вопроса: команда не знает, что этот адрес — выдача прав. Про удаление она спрашивает, потому что судит по методу (DELETE).

    Вариант Цена
    А Оставить: ycli api — выход «мимо обёрток», кто им пользуется, тот знает адрес ноль; пометка не защищает от прямого запроса
    Б ycli api сверяет метод и адрес с помеченными операциями и спрашивает сопоставление адреса с шаблонами путей 14 операций; новое место, где адреса сравниваются
    В ycli api спрашивает перед любой записью (POST, PUT, PATCH), как перед удалением ломает скрипты с ycli api -X POST без --yes

    Рекомендация: А сейчас, с одной фразой в справке ycli api; Б — если защита должна быть полной.

    Вопрос 2. Что ещё выдаёт доступ, но не помечено

    Вы решили начать с базового набора. Ревью перечислило операции, которые тоже что-то передают; ни одна не противоречит решению, это список на расширение:

    Что передаётся Операции
    Владение или ответственный wiki pages update с owner; tracker queues create (lead); tracker components / projects create и update (lead); tracker boards create (owner, шаблон прав, по умолчанию public); tracker dashboards create (owner)
    Доступ через тело другой операции wiki pages create с политикой доступа; tracker entities create / update / update-bulk (участники, клиенты, наблюдатели); tracker issues update (наблюдатели и поля доступа)
    Наследуемые права меняются при переносе wiki pages move / clone; datalens workbooks / collections move и move-bulk
    Ссылка, работающая без учётных данных datalens cloudenvironmentstorage bucket-download-url-create / bucket-upload-url-create
    Данные уходят наружу datalens workbookexports start / result-get; forms answers export; forms hooks и subscriptions; tracker triggers, autoactions, macros
    Прочее datalens licensing limit-set; datalens connections create / update (сохранённые учётные данные источника); любое поле через -F / --body-file

    Список составлен чтением моделей запросов; как эти поля ведут себя на живом API, не проверялось.

    Нужно от вас: «1 — А / Б / В»; по списку — что из него пометить сейчас, если что-то, или оставить на потом.

  7. bim-ba commented on Oct 11, 2026

    @bim-ba
    OwnerAuthor

    1 - А
    2 - предлагаю вынести в отдельный Issue и добавлять потихоьнку потом

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs:decisionWaiting for an owner decision

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions