Ограничение инструментов агента

Почему это важно именно вам

Представьте, что вы наняли аналитика для работы с данными по конкурентам. Его задача — читать отчёты, сравнивать цифры, делать выводы. Вы даёте ему папку с документами. Но этот аналитик, пока работает, ещё и начинает переименовывать файлы, удалять «лишние», отправлять кому-то письма и устанавливать программы — потому что технически может. Вы не просили, он просто «помогал». Примерно так выглядит субагент Claude без ограничения инструментов.

Директор по развитию работает с разными агентами под разные задачи. Аналитик изучает договоры и находит риски. Редактор правит тексты. Нотификатор отправляет уведомления. Каждый из них технически способен делать многое — читать файлы, запускать команды, изменять данные. Но для своей задачи ему нужен только узкий набор операций. Всё остальное — потенциальная зона ошибок.

Поле tools в конфигурации субагента решает именно эту проблему. Вы явно указываете, что агент может делать — и больше ничего. Аналитик только читает. Редактор только правит текст. Нотификатор только запускает нужный скрипт. Не потому что вы не доверяете Claude — а потому что чёткие границы делают работу предсказуемой. Агент не отвлекается на лишнее, не принимает решений за вас и не делает то, что вы не просили.

Что это такое

В каждом субагенте (файл .claude/agents/имя.md) есть frontmatter — блок настроек в начале файла. Там можно указать поле tools: список инструментов, которые этому агенту разрешены. Если поле не указано — агент получает всё доступное по умолчанию. Если указано — только то, что в списке. Нюанс с фоном: в интерактивной сессии субагенты уходят в фон, а фоновому агенту достаётся сокращённый набор встроенных инструментов (Read, Grep, Glob, Bash, Edit, Write, WebFetch, WebSearch и ещё несколько) — остальные система уберёт, даже если вы их прописали.

Аналогия: корпоративная карта доступа. Когда сотрудник приходит в офис, его пропуск открывает только нужные двери. Аналитик проходит в переговорные и к своему столу — но не в серверную и не на склад. Не потому что он плохой сотрудник, а потому что для его работы эти двери не нужны. Если что-то пойдёт не так, зона риска ограничена.

Есть и обратный подход — поле disallowedTools. Это не список разрешений, а список запретов: агент получает всё, кроме указанного. Как ситуация, когда у сотрудника полный доступ, но серверная закрыта отдельным замком.

Оба подхода решают одну задачу — сужение зоны влияния агента. Но философия разная. tools говорит: «только это». disallowedTools говорит: «всё, кроме этого». Для агентов с узкой задачей предпочтителен tools — он точнее. Для агентов с широкой задачей, где нужно ограничить пару опасных операций, подходит disallowedTools.

Принцип минимальных прав

В информационной безопасности есть принцип least privilege — давать системе ровно те права, которые нужны для работы, и ни одного лишнего. Это не про недоверие, а про предсказуемость. Если у агента нет инструмента — он не сможет его использовать случайно или по ошибке. Никаких неожиданных правок, никакой «инициативы» за пределами задачи.

Как работает на практике

Начнём с конкретных примеров. У вас три типичных агента для работы директора: аналитик документов, редактор текстов, нотификатор. Разберём каждый.

Агент 1: Аналитик документов

Задача: читать договоры, отчёты, протоколы совещаний и извлекать информацию. Создавать, изменять или удалять файлы ему не нужно.

Файл .claude/agents/analyst.md:

---
name: analyst
description: Читает документы и извлекает структурированную информацию. Не изменяет файлы.
tools:
  - Read
  - Grep
  - Glob
---

Ты аналитик документов. Читаешь файлы, ищешь информацию, делаешь выводы.
Не создаёшь и не изменяешь файлы. Только анализируй и отвечай.

Когда находишь риски в договоре — указывай конкретный пункт и формулировку.
Когда сравниваешь данные — показывай цифры, не пересказывай.

Что здесь происходит: агент получает три инструмента.

Read — читать файлы
Grep — искать по содержимому (как поиск по тексту, но мощнее)
Glob — находить файлы по шаблону (например, все *.pdf в папке)

Этого достаточно, чтобы прочитать любой документ и найти нужную информацию. Но агент не может запустить программу, создать файл, изменить текст или выйти в интернет. Зона риска — ноль.

Агент 2: Редактор текстов

Задача: получить текст, улучшить формулировки, исправить стиль. Запускать программы, читать чужие файлы или изменять что-то, кроме переданного текста, — не нужно.

Файл .claude/agents/editor.md:

---
name: editor
description: Редактирует тексты — деловые письма, отчёты, презентации. Не запускает программы.
tools:
  - Read
  - Edit
  - Write
---

Ты редактор деловых текстов. Улучшаешь стиль, убираешь жаргон, делаешь тексты чище.

Правила:
- Сокращай без потери смысла
- Убирай корпоративный язык: «осуществлять», «данный», «в рамках»
- Сохраняй тон оригинала: если автор пишет официально — оставляй официально
- Не меняй факты, цифры, имена

Три инструмента: Read (прочитать исходный файл), Edit (внести правки), Write (записать результат). Bash, Grep, MCP-инструменты — недоступны. Редактор не может случайно запустить скрипт или залезть в чужие папки.

Когда давать Write, а когда нет

Write позволяет создавать новые файлы. Если агент только исправляет существующий текст и сохраняет его обратно — достаточно Edit. Если агент должен создать новый файл с результатом — добавьте Write. Разница важна: Edit меняет существующий файл, Write создаёт новый.

Агент 3: Нотификатор

Задача: запустить конкретный скрипт или команду для отправки уведомления. Читать файлы, изменять их или делать анализ — не нужно.

Файл .claude/agents/notifier.md:

---
name: notifier
description: Запускает скрипты уведомлений. Не читает и не изменяет файлы проекта.
tools:
  - Bash
disallowedTools:
  - Read
  - Edit
  - Write
---

Ты нотификатор. Твоя единственная задача — запускать команды для отправки уведомлений.

Команды, которые можешь использовать:
- `python notify.py --message "..."` — отправить уведомление
- `bash send_alert.sh` — запустить алерт

Не запускай ничего другого без явного запроса.

Здесь disallowedTools добавлен как страховка и как документация намерения: tools: Bash уже отсекает файловые инструменты, но явный запрет защитит, если кто-то потом расширит tools. Для нотификатора это логично: ему нужен Bash, но не нужен доступ к файловой системе.

Основные инструменты Claude Code

Прежде чем прописывать tools, полезно знать, что вообще доступно:

Read — читать содержимое файлов
Write — создавать новые файлы
Edit — вносить правки в существующие файлы
Bash — выполнять команды в терминале
Grep — искать по содержимому файлов (регулярные выражения, текстовый поиск)
Glob — находить файлы и папки по шаблону (например, все *.docx в папке)
WebFetch — загружать содержимое веб-страниц по URL
WebSearch — выполнять поиск в интернете

Плюс инструменты MCP-серверов, если они подключены — они добавляются отдельно при конфигурации.

Для большинства агентов директора достаточно первых четырёх-пяти. WebFetch и WebSearch нужны редко — обычно только если агент должен проверять актуальную информацию из сети.

Как выглядит вызов агентов

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

claude "Проверь договор с поставщиком на предмет штрафных санкций" --agent analyst

или через оркестратор, который сам решает, какой агент нужен.

Что происходит, если агент пытается использовать запрещённый инструмент

Агент не молча игнорирует запрет — он сообщает, что инструмент недоступен, и либо ищет обходной путь в рамках разрешённого, либо отвечает, что задача требует инструмента, которого у него нет. Это именно то, что нужно: явный сигнал вместо тихой ошибки или неожиданного результата.

Если агент часто жалуется на нехватку какого-то инструмента — это сигнал пересмотреть список tools. Либо задача шире, чем вы думали, и инструмент нужен. Либо промт агента слишком широкий и захватывает сценарии, которые не входили в исходное назначение.

Поле tools не фильтрует аргументы команд

tools: [Bash] разрешает запускать команды через Bash, но не ограничивает, какие именно команды. Ограничить конкретные команды можно технически: правилом разрешений с шаблоном — Bash(python notify.py *) в permissions.allow — или хуком PreToolUse, который проверяет команду до запуска. Инструкция в промте — самый слабый из трёх способов. Поле tools работает на уровне типов инструментов, не на уровне конкретных операций внутри них.

Частые ошибки

Ошибка 1: Давать все инструменты «на всякий случай»

Логика понятна: «а вдруг агенту понадобится что-то ещё». Но это отменяет весь смысл ограничений. Агент с полным набором инструментов — агент без ограничений. Если задача аналитика — только читать, то Write и Bash ему не нужны никогда. Не «почти никогда», а никогда.

Как исправить: перед тем как добавить инструмент, задайте вопрос — «в каком конкретном сценарии этот агент будет это использовать?». Если ответ размытый — инструмент лишний.

Ошибка 2: Путать tools и disallowedTools

Начинающие иногда пишут оба поля одновременно с пересекающимися инструментами. Например, tools: [Read, Edit] и disallowedTools: [Edit]. Порядок здесь определён: сначала применяется disallowedTools, потом tools разрешается по остатку — агент получит только Read. Не «непредсказуемо», но запутанно. Правило простое: выберите один подход.

Если нужный список короткий — используйте tools. Если разрешено почти всё, кроме пары опасных операций — используйте disallowedTools. Смешивать их стоит только в обоснованных случаях — как в примере с нотификатором выше, где нужен Bash, но не нужен доступ к файлам.

Ошибка 3: Забыть про инструменты MCP

Стандартные инструменты Claude Code — это Read, Edit, Write, Bash, Grep, Glob. Но если у вас подключены MCP-серверы (об этом — в фазе 6), они добавляют свои инструменты. Если агенту они не нужны — их тоже стоит явно исключить через disallowedTools, иначе агент получит доступ к базам данных, внешним сервисам или API, которые ему не нужны.

Как исправить: после подключения нового MCP-сервера пройдитесь по существующим агентам и проверьте, нужны ли им новые инструменты. Если нет — добавьте в disallowedTools.

Ошибка 4: Слишком строгие ограничения, которые мешают работе

Если агенту дать только Read, но поставить задачу, которая требует хотя бы Grep, он либо откажется работать, либо начнёт использовать обходные пути. Это хуже, чем нормальный набор инструментов.

Как исправить: тестируйте агента после настройки. Дайте реальную задачу и посмотрите, справляется ли он. Если жалуется на нехватку инструментов или выдаёт неожиданные решения — пересмотрите список. Цель — минимально достаточный набор, не минимально возможный.

Ограничения защищают не только данные, но и сам агент

Агент без лишних инструментов меньше отвлекается. Если у аналитика нет Bash — он не будет пытаться запустить что-то «для удобства». Ограничения фокусируют агента на задаче. Это влияет на качество работы, а не только на безопасность.

Когда нужно / когда нет

Нужно, если:

Агент работает с важными файлами, которые нельзя случайно изменить или удалить — договоры, финансовые отчёты, реестры клиентов
Несколько агентов работают в одной папке, и нужно чётко разграничить, кто что может
Агент выполняет автоматические задачи без вашего участия (например, по расписанию) — тогда зона риска особенно важна
Агент будет использоваться регулярно, его настройка — инвестиция, а не разовый эксперимент

Не нужно или менее критично, если:

Агент используется разово для одной конкретной задачи под вашим контролем — достаточно следить за шагами в диалоге
Задача принципиально требует широкого набора операций — например, оркестратор, который управляет другими агентами, по определению должен иметь доступ к широкому набору инструментов
Вы только начинаете работать с агентом и ещё не знаете, какие инструменты ему нужны — сначала дайте полный набор, понаблюдайте, потом сократите

Ограничения vs промт

Поле tools работает на уровне системы — агент физически не сможет вызвать запрещённый инструмент. Инструкции в промте («не изменяй файлы») работают на уровне поведения — агент постарается следовать, но в теории может нарушить при необычном запросе. Для критичных ограничений — всегда используйте tools, не только промт.

Практический вопрос: с чего начать, если агенты уже написаны без ограничений?

Не нужно переделывать всё сразу. Начните с одного агента, который работает с самыми важными данными. Посмотрите в его файл и задайте себе вопрос: «Если этот агент по ошибке изменит или удалит что-то — насколько это критично?». Если ответ «очень критично» — ограничения нужны прямо сейчас. Если «не критично» — можно отложить.

Связь с другими уроками

День 22: .claude/agents/ — там мы разбирали, как создавать агентов и запускать их. Сегодняшний урок — следующий шаг: когда агенты созданы, нужно настроить их права. Если пропустили урок 22 — стоит вернуться: без понимания структуры файла агента поле tools некуда добавить.

День 23: Frontmatter субагентов — поля tools и disallowedTools живут именно в frontmatter файла агента, рядом с name, description и другими параметрами. В уроке 23 разобрана полная структура этого блока — туда же добавляются инструментальные ограничения.

День 29: Безопасность агентной системы — ограничение инструментов это один слой защиты. В уроке 29 разберём полную картину: как организовать систему агентов, чтобы она не только работала эффективно, но и не могла нанести вреда при ошибке или неожиданном входящем запросе.

Задание на сегодня

Откройте любой существующий файл агента в .claude/agents/ — или создайте новый минимальный агент для одной конкретной задачи. Добавьте в frontmatter поле tools с двумя-тремя инструментами, которые реально нужны для этой задачи.

Критерий «выполнено»: агент запущен, выполнил задачу с ограниченным набором инструментов. Если при работе он не жаловался на нехватку инструментов и справился с задачей — список достаточен. Если жаловался — добавьте нужный инструмент и запустите снова.

Не нужно переделывать всех агентов сразу. Одного достаточно, чтобы понять принцип.

Резюме

Поле tools в frontmatter субагента ограничивает набор доступных инструментов: агент может использовать только то, что явно указано.
disallowedTools работает наоборот: агент получает всё, кроме запрещённого. Подходит, когда разрешено почти всё, но нужно закрыть пару опасных операций.
Принцип: минимально достаточный набор. Аналитик — только Read, Grep, Glob. Редактор — Read, Edit, Write. Нотификатор — только Bash.
Ограничения инструментов работают надёжнее, чем инструкции в промте: агент физически не сможет вызвать запрещённый инструмент, а не просто постарается не вызывать.
Начинать переделку стоит с агентов, которые работают с важными данными — там цена ошибки выше всего.