dsh-agent-tool-filter

English version: see README.en.md.

Per-agent фильтр инструментов основного агента (ведущего задачу) для DeepSeek Harness.

Цель — независимые наборы tools: выбранные пресеты работают с обрезанным набором (экономия на tool-схемах в каждом запросе), субагенты сохраняют полный набор, включая web. Штатного per-agent фильтра для основного агента в DSH нет.

Важно перед установкой

1. Возможности плагина могут пересечься с обновлениями DSH. Функциональность per-agent фильтрации со временем может быть встроена в саму платформу. Прежде чем устанавливать плагин, проверьте актуальную версию DSH и список её обновлений: если нужные возможности уже доступны штатно, отдельный плагин не требуется.
2. Фильтрация действует только на основного агента. Скрытые инструменты у него отключаются; у субагентов они остаются доступными — плагин не переносит ограничения автоматически. Чтобы ограничение стало сквозным:
   • настройте для каждого субагента собственный пресет с подходящим набором инструментов. Например, для веб-поиска оставьте субагенту только web-инструменты и read; для других сценариев выберите свои наборы;
   • пропишите основному агенту рабочие сценарии: когда задача требует скрытого инструмента — не пытаться вызвать его напрямую, а передать задачу субагенту, у которого этот инструмент доступен. Без этих настроек агент будет упираться в отключённые инструменты вместо делегирования — фильтрация сработает, но рабочий процесс сломается.

Ограничение набора инструментов через пресет не подходит для этой задачи: оно фиксируется при создании чата и наследуется субагентами, ограничивая их вместе с основным агентом. Маска плагина применяется только к основному агенту и может меняться без этих ограничений.

Механика

1. На событии agent/created (listeners отрабатывают до первой сборки prompt) плагин определяет пресет агента (agentPresets.composedPreset(agent.ctx)) и по конфиг-матрице «пресет → профиль» выбирает профиль фильтрации.
2. Ограничение ставится в scope самого агента: agent.ctx.tools.restrict(...). Фильтруются только корневые агенты: in-process субагенты присоединяются к пресету родителя (composeFrom) и показывают тот же пресет — без проверки roots() фильтр задел бы субагентов. SDK-субагенты живут в отдельном процессе и не задеваются вовсе.
3. Маски restrict() пересекаются, поэтому при смене конфига старые ограничения снимаются (disposers), а новые ставятся заново. Состояние хранится на самом агенте и переживает hot-reload плагина.
4. Собственные registrations scope (structured-output и пр.) restrict() не маскирует.

Конфигурация

Пакет устанавливается как bundle через Plugin Manager и сам предоставляет строку плагина. Настройте матрицу и профили в UI-карточке; изменения применяются горячо (HMR). Ниже — пример значений конфигурации:

- insert:
    - id: agent-tool-filter
      name: dsh-agent-tool-filter
      config:
        enabled: true
        presets:                    # матрица «id пресета → имя профиля»; пусто = не фильтровать нигде
          cordis: cordis-trim
          standard: minimal-orchestrator
        profiles:                   # свои профили и правка дефолтных (переопределяют по имени)
          my-profile:
            mode: deny              # deny — убрать перечисленные; allow — оставить только их
            tools: [web_search, web_fetch]

Поле	Дефолт	Значение
enabled	true	false — плагин пассивен
presets	пусто	матрица «пресет → профиль»; пусто = ничего не фильтровать (установка не меняет поведение пресетов)
profiles	встроенные (см. ниже)	пользовательские профили; совпадение имени перекрывает встроенный
language	auto	язык UI плагина: auto — как в приложении, либо ru / en

Профили фильтрации и шаблоны

По умолчанию установлен один универсальный профиль; остальные добавляются импортом пакетов-шаблонов прямо из UI-карточки.

Профиль/пакет	Содержимое (deny)	Идея
balanced (встроенный)	админ: plugin_manager, security_audit, test_drive, drive_report, create_skill, subagent_fork	базовая обрезка для любого пресета
пакет gradient	strict (админ + web), soft (web)	ступени ограничения вокруг balanced
пакет roles	focus, no-web, no-admin, minimal	профили по назначению
пакет layers	no-web, no-admin, no-dev-skills	одна категория = один профиль, комбинируйте копиями

Любой профиль можно скопировать и править под себя (свои списки tools, режим deny/allow); встроенный balanced переопределяется по имени, но не удаляется.

Что делает установка

Пакет не добавляет пресетов, инструментов и чужой конфигурации — только файлы плагина и bundle-строку с безопасной конфигурацией по умолчанию. При первой активации плагин сканирует установленный DSH (реальные tools и пресеты) и сверяет профили обрезки с вашим набором; отчёт — в лог. Фильтрация выключена до тех пор, пока вы не свяжете пресет с профилем (матрица presets). Подробная инструкция — docs/filtering-guide.md.

UI

UI-карточка (v1.0.0) открывается из Plugin Manager: строка dsh-agent-tool-filter → Configure. В карточке:

• тумблер «Фильтрация включена» и статус (агенты с маской, скрыто схем);
• матрица «пресет → профиль» карточками в два блока (дефолтные и кастомные): связка/замена/снятие профиля, копия пресета (с предпросмотром описания) и удаление кастомных;
• профили: создание/правка/копия в модальных окнах, три группы tools (включённые, управляемые, неуправляемые), импорт пакетов-шаблонов;
• сканирование tools — сводка по палитре DSH («✅ N tools можно отключить / ⚠ M tools нельзя отключить») и предупреждения с причинами;
• диагностика — свёрнутый блок с техническими данными (remote, locale, версия, счётчики);
• интерфейс на русском и английском (переключатель языка, режим «Как в приложении»); в Plugin Manager также доступны русские и английские метаданные и оригинальная иконка плагина.

Валидация имён и диагностика

• При старте и по scanTools() плагин сверяет имена профилей с глобальным списком tools. Неизвестные и нефильтруемые имена (own-layer registrations: team_task_*, spawn_teammate, wait_agent) попадают в предупреждения (лог и UI-карточка), а не в тихий пропуск.
• restrict() дополнительно проверяет имена при применении: неизвестное имя не блокирует остальные (deny применяется поимённо), ошибка попадает в лог с перечнем пропущенных.
• Диагностика: «сколько схем скрыто текущим фильтром» — в логе (строка применения) и в agentToolFilter.status().agents[].hidden.
• Файловая диагностика под тумблером debugLog (по умолчанию выкл), ATF_DEBUG_LOG — принудительное включение с путём файла.

Совместимость с провайдерами

Режим работы плагин выбирает автоматически — отдельных настроек для этого нет.

• Строгие провайдеры сверяют вызовы инструментов из истории диалога с текущим списком tools: если схема инструмента скрыта, а в истории есть его вызовы, запрос завершается ошибкой провайдера («Провайдер вернул некорректный вызов инструмента»). Мягкие провайдеры такую историю принимают.
• Если история агента уже содержит вызовы скрываемых инструментов, плагин временно не скрывает схемы, а вызовы скрываемых инструментов блокирует с подсказкой делегировать задачу субагенту — так история и список инструментов не расходятся ни у строгих, ни у мягких провайдеров.
• После сжатия истории чат переходит на обычное скрытие схем — экономия контекста включается автоматически (проверено: после сжатия скрытые схемы исчезают из запроса модели).
• Если скрываемые инструменты в чате никогда не вызывались — скрытие схем включается сразу, даже в старом чате (проверено: чат работает без ошибок).

Обратимость (памятка)

• Выключение (enabled: false) и правки конфига действуют на новых агентов (создание/resume/clear). Для живого сеанса надёжный путь — перезапуск DSH или пересоздание агента (clear/resume): scope агента пересоздаётся, фильтр применяется заново.
• Плагин дополнительно пытается применить изменения к живым агентам сразу (hot-apply при app-boot/config-reload), но полагаться на это как на единственный путь не стоит.
• Снятие фильтра у конкретного агента без перезапуска: удалить пресет из матрицы presets и пересоздать агента; ограничения снимаются со scope агента автоматически при dispose.
• restrict() — ограничение видимости для модели (и экономия на схемах), НЕ sandbox и не гарантия безопасности.

Установка

В Plugin Manager установите пакет через plugin_manager → install_bundle, указав путь к релизному .tgz или к каталогу распакованного пакета. Для npm-пакета сначала получите его в доступном окружению каталоге, затем передайте путь к каталогу пакета в install_bundle. Менеджер установит и подключит bundle; вручную править профильный cordis.patch.yml или распаковывать пакет в профиль не нужно. Первую активацию при необходимости завершите перезапуском DSH. Зависимостей у пакета нет; модули @deepseek-ai/* предоставляет хост.