Инструменты
Встроенные инструменты, с помощью которых агент читает, правит, ищет, выполняет команды, поручает задачи и задаёт вопросы, и чем они различаются у разных семейств моделей.
Агент действует через инструменты. Имена инструментов Cusp и поля их ввода (Read, Edit, Bash, file_path, old_string, …) — те, под которые написаны существующие хуки, правила разрешений и навыки, поэтому они работают без изменений.
Каждый вызов проходит один и тот же путь: проверка и исправление входных данных, хуки PreToolUse, движок разрешений, сам инструмент, затем хуки PostToolUse. Вызовы только для чтения из одного пакета выполняются параллельно.
Встроенные инструменты
Файлы
| Инструмент | Что делает |
|---|---|
Read | Читает файл с номерами строк. По умолчанию до 2000 строк; offset и limit задают диапазон, а отрицательный offset читает с конца. Также читает изображения, PDF (до 20 страниц за вызов) и блокноты Jupyter |
Write | Создаёт или перезаписывает файл, при необходимости создавая родительские каталоги |
Edit | Заменяет точную строку в файле. Завершается ошибкой, если текст не уникален, если только не задан replace_all |
MultiEdit | Несколько замен в одном файле, применяемых атомарно |
ApplyPatch | Применяет патч V4A, который может атомарно добавлять, обновлять, перемещать и удалять несколько файлов. Модели семейства GPT видят его как apply_patch |
EditLines | Правит по привязкам строк из последнего Read. Используется для слабых и локальных моделей |
NotebookEdit | Заменяет, вставляет или удаляет одну ячейку в блокноте .ipynb |
Поиск
| Инструмент | Что делает |
|---|---|
Grep | Ищет по содержимому файлов с помощью регулярного выражения (семантика ripgrep). Использует rg, если он установлен, иначе — встроенный движок с идентичным выводом |
Glob | Находит файлы по шаблону имени, например src/**/*.{ts,tsx} |
LS | Выводит содержимое каталога в виде дерева с размерами файлов |
Оболочка
| Инструмент | Что делает |
|---|---|
Bash | Выполняет команду оболочки и возвращает её вывод. Тайм-аут по умолчанию 120 с, максимум 600 с |
Process | Запускает долго работающие процессы, такие как серверы разработки и наблюдатели за файлами, и управляет ими. Ждёт, пока порт, URL или строка в логе не покажут, что процесс готов |
Terminal | Управляет интерактивной программой через псевдотерминал: REPL, отладчики, ssh, интерактивные запросы, терминальные интерфейсы |
Веб
| Инструмент | Что делает |
|---|---|
WebFetch | Загружает публичную страницу и возвращает её в виде Markdown. Отказывается обращаться к адресам частной сети и сообщает о перенаправлениях на другие хосты, а не следует им |
WebSearch | Ищет в интернете и возвращает заголовки, URL и фрагменты |
Планирование и диалог
| Инструмент | Что делает |
|---|---|
TodoWrite | Ведёт список задач сессии. Модели семейства GPT вместо него используют UpdatePlan (update_plan) |
AskUserQuestion | Задаёт вам от одного до четырёх вопросов с вариантами ответа, когда агент упирается в решение, которое должны принять вы |
EnterPlanMode, ExitPlanMode | Переход в режим планирования и представление плана на одобрение |
Skill | Загружает навык |
ToolSearch | Загружает отложенные инструменты по имени или ключевому слову |
Агенты
| Инструмент | Что делает |
|---|---|
Agent | Запускает субагента с чистым контекстом для самостоятельной задачи |
SendMessage | Отправляет сообщение другому агенту: субагенту, участнику команды или другой сессии |
ListAgents | Показывает список агентов, которым можно написать |
Анализ кода
| Инструмент | Что делает |
|---|---|
Diagnostics | Сообщает об ошибках и предупреждениях компилятора и языкового сервера для файлов |
LSP | Запросы к языковому серверу только для чтения: переход к определению или реализации, поиск ссылок, подсказки при наведении, символы документа и рабочей области, иерархия вызовов |
Что стоит знать о поведении
Сначала чтение, потом правка. Агент должен прочитать файл, прежде чем его править. Cusp запоминает размер файла и время изменения на момент чтения и проверяет их снова прямо перед записью, поэтому правка никогда не попадёт в файл, который успел измениться. Частичное чтение позволяет править только те строки, которые были прочитаны.
Нечёткое сопоставление с отчётом. Если old_string в Edit не совпадает точно, Cusp пробует всё более мягкие варианты сопоставления (нормализованные пробелы, обрезанные концы строк, повторный отступ, привязка к блоку). Он сообщает, какой уровень сработал, и отвергает совпадения, подозрительно отличающиеся по размеру.
Диагностика после правок. После правки Cusp запускает подходящую проверку (tsgo или tsc для TypeScript либо языковой сервер) и добавляет новые ошибки к результату инструмента. Агент видит внесённую им ошибку типов на том же шаге.
Предсказуемая оболочка. Каждая команда Bash выполняется неинтерактивно: stdin закрыт, а пейджеры отключены (PAGER=cat, GIT_PAGER=cat), поэтому ничего не зависает в ожидании ввода. Рабочий каталог сохраняется между вызовами, пока остаётся внутри рабочей области. Секреты удаляются из окружения. Команда, превысившая тайм-аут, не завершается принудительно, а переводится в фон, и агент получает уведомление, когда она завершится.
Коды выхода с учётом контекста. Код выхода 1 у grep, rg, find, diff, test и git diff означает «нет совпадений» или «есть различия» и не считается ошибкой.
Большой вывод уходит в артефакты. Вывод длиннее примерно 30 000 символов обрезается до начала и конца, а полный текст сохраняется как артефакт. Агент может прочитать его через Read или Grep как artifact:<id>, так что ничего не теряется, а контекст остаётся небольшим.
Инструменты для разных семейств моделей
Каждое семейство моделей получает тот набор инструментов, с которым его обучали работать. Хуки и правила разрешений всегда видят каноническое имя из первого столбца.
| Инструмент | Claude | GPT | Gemini | Слабые и локальные модели |
|---|---|---|---|---|
Read | ✓ | ✓ | ✓ | ✓ (с привязками строк) |
Edit, MultiEdit | ✓ | — | ✓ | — |
ApplyPatch | — | как apply_patch | — | — |
EditLines | — | — | — | ✓ |
Write | ✓ | ✓ | ✓ | ✓ |
TodoWrite | ✓ | — | ✓ | ✓ |
UpdatePlan | — | как update_plan | — | — |
| Все остальные | ✓ | ✓ | ✓ | ✓ |
Отложенные инструменты
Каждое определение инструмента занимает контекст на каждом ходе. Полезные, но редко нужные инструменты откладываются: модель видит только их имена и загружает полное определение через ToolSearch, когда оно нужно.
Отложены по умолчанию: Terminal, NotebookEdit, Diagnostics, LSP и все инструменты MCP.
Загруженные инструменты добавляются после основных, поэтому начало промпта остаётся побайтово одинаковым от хода к ходу, и кеш промптов у провайдера продолжает работать.
Инструменты MCP
Инструменты MCP-серверов отображаются как mcp__<server>__<tool>. Они отложены, если сервер не пометил их как всегда загружаемые. Два дополнительных инструмента, ListMcpResourcesTool и ReadMcpResourceTool, читают ресурсы, которые предоставляют серверы.
Как ограничить инструменты
- Запретите инструмент для всех правилом разрешений:
"deny": ["WebSearch"]. - Запретите его для одного запуска:
cusp --disallowedTools WebFetch. - Дайте субагенту или навыку более узкий набор через
tools:илиallowed-tools:во frontmatter.
Полная спецификация
Точные описания и JSON-схемы, которые видит модель, генерируются из реестра инструментов и опубликованы в репозитории в файле docs/specs/harness-tools.md.