18. Каталог встроенных tools — AstraCode — Техническая документация

Tool — это функция, которую модель может вызвать в ходе своего ответа (через function_call в OpenAI API / tool_use в Anthropic API). Точный набор зависит от feature flags, collaboration mode и провайдера; кроме встроенных tools доступны динамические MCP/custom tools.

Реализация — крейт tools/. Реестр и диспетчеризация — core::tools (см. 19-agent-loop.md).

1. Архитектура

Типы спецификаций

В tools/src/tool_spec.rs:

rust

pub enum ToolSpec {
    Function { name, description, parameters, strict, supports_parallel_tool_calls },
    Namespace { name, tools },           // группа tools под одним именем
    LocalShell,                          // OpenAI built-in local_shell
    Freeform(FreeformTool),              // grammar-based (например, apply_patch); сериализуется как `type: "custom"`
}

FreeformTool содержит поля name, description и format: FreeformToolFormat (где format.type = "grammar", format.syntax = "lark", format.definition = <грамматика Lark>). См. tools/src/responses_api.rs:12 и tools/src/apply_patch_tool.rs:88.

Реестр и handlers

Регистрация — build_tool_registry_plan() в tools/src/tool_registry_plan.rs. Возвращает ToolRegistryPlan — список ConfiguredToolSpec (имя + JSON schema + флаг supports_parallel_tool_calls) и соответствующий ToolHandlerSpec для маршрутизации в core.

Enum ToolHandlerKind (tools/src/tool_registry_plan_types.rs) перечисляет 32 типа handler'а: Shell, ShellCommand, UnifiedExec, ApplyPatch, WriteFile, Goal, Plan, Mcp, McpResource, SpawnAgentV1/V2, WaitAgentV1/V2, CloseAgentV1/V2, SendInputV1, SendMessageV2, ResumeAgentV1, ListAgentsV2, FollowupTaskV2, AgentJobs, CodeModeExecute, CodeModeWait, RequestUserInput, RequestPermissions, ListDir, ViewImage, SearchInFiles, AstraCodeHelp, DynamicTool, TestSync, ToolSuggest.

Sandbox и approvals

Каждый tool маршрутизируется в core::tools::router (см. 19-agent-loop.md) — там применяются permission_profile и approval_policy сессии. Подробнее — 09-security.md.

2. Выполнение команд

`exec_command`

Файл: tools/src/local_tool.rs:19-89.

Выполнение команды в PTY (unified exec). Может удерживать долгоиграющую сессию.

Параметр	Тип	Описание
`cmd`	string	Команда (передаётся в shell)
`workdir`	string?	Рабочая директория
`shell`	string?	`bash`/`zsh`/… (по умолчанию — sticky shell сессии)
`tty`	bool?	Использовать PTY
`yield_time_ms`	int?	Сколько ждать вывода перед возвратом (для long-running)
`max_output_tokens`	int?	Лимит токенов в ответе
`login`	bool?	Login-shell (`bash -l`)

Возвращает текст output + опционально session_id (если процесс продолжает работать).

Sandbox: проходит через permission_profile (read/write/shell/network). Approval: по политике (untrusted/on-failure/never).

Parallel calls: ✓ (если sandbox разрешает).

`write_stdin`

Файл: tools/src/local_tool.rs:92-133.

Запись в stdin активной unified-exec сессии. Использует session_id от предыдущего exec_command.

Параметр	Тип	Описание
`session_id`	number	Числовой ID активной unified-exec сессии
`chars`	string	Что отправить в stdin
`yield_time_ms`	int?	Сколько ждать вывода
`max_output_tokens`	int?	Лимит токенов

Parallel calls: ✗ (serial по своей природе).

`shell` (legacy)

Файл: tools/src/local_tool.rs:136+.

Простой однократный shell: получает command: ["arg0", "arg1", ...] массивом и опциональный workdir. Не использует PTY, не держит сессии. Parallel calls: ✓.

`shell_command`

Альтернативная форма exec_command для legacy провайдеров. Handler: ToolHandlerKind::ShellCommand.

3. Редактирование файлов

`apply_patch`

Файл: tools/src/apply_patch_tool.rs:89-98.

Freeform tool с grammar (Lark) — не JSON, а специальный формат патчей:

text

*** Begin Patch
*** Update File: path/to/file.rs
@@ context line
- old line
+ new line
*** End Patch

Поддерживает операции: - *** Add File: — создать файл (с содержимым). - *** Update File: — изменить (с контекстом). - *** Delete File: — удалить.

Approval: по политике; в workspace-write патч в .git/.astracode блокируется sandbox'ом.

Реализация применения — крейт apply-patch/. Поддерживает многосекционные патчи.

Parallel calls: ✗ (изменения файлов сериализуются).

`write_file`

Файл: tools/src/utility_tool.rs:63-92.

Создаёт новый файл или полностью перезаписывает существующий заданным содержимым. Для точечных правок используйте apply_patch. Лимит: 64 KB содержимого. Перед полной перезаписью существующего файла модель должна прочитать его, чтобы не потерять невидимый контекст.

Параметр	Тип	Описание
`path`	string	Абсолютный путь к файлу
`content`	string	Полное новое содержимое (создаёт или полностью перезаписывает)

Handler: WriteFile. Approval: по политике (write FS). Parallel calls: ✗.

4. Multi-agent (v1 и v2)

Agent — это вложенный AstraCode-поток, который parent может запустить как worker. Используется для декомпозиции задач (один агент координирует, sub-agents выполняют части параллельно).

По умолчанию AstraCode использует стабильный v1 API: feature multi_agent включён, а экспериментальный multi_agent_v2 имеет статус UnderDevelopment и выключен. При включении multi_agent_v2 реестр целиком заменяет v1-набор tools на v2-набор; одновременно они модели не выдаются.

v1 API (основной)

spawn_agent (agent_tool.rs:28-51)

Параметр	Тип	Описание
`message`	string?	Начальное текстовое задание; используется либо `message`, либо `items`
`items`	array?	Структурированный ввод: text/image/local_image/skill/mention
`agent_type`	string?	Роль sub-agent'а; может менять инструкции и назначенную через `/submodel` пару provider/model
`fork_context`	bool?	При `true` передать очищенную историю parent thread; по умолчанию `false`

Возвращает agent_id (UUID thread) и опциональный nickname. Без явного fork_context: true новый агент не получает transcript родителя, хотя наследует runtime config, cwd, permissions и sandbox. При полном fork передаются user-сообщения и финальные ответы assistant; reasoning, промежуточные commentary и tool calls/results отфильтровываются. Parallel calls: ✗.

send_input (agent_tool.rs:89-121) — отправляет существующему агенту message или items. Параметр interrupt: true останавливает текущую задачу и немедленно переключает агента на новый ввод; при false ввод ставится в очередь.

wait_agent — ждёт финальный статус одного из UUID, перечисленных в targets; принимает опциональный timeout_ms и может вернуть финальный ответ агента. Handler: WaitAgentV1.

close_agent — завершает указанный по UUID sub-agent thread и его открытых потомков. Handler: CloseAgentV1.

resume_agent — повторно открывает ранее закрытого агента по UUID, чтобы ему снова можно было отправлять send_input и ждать его через wait_agent. Handler: ResumeAgentV1.

v2 API (экспериментальный, по умолчанию выключен)

Включается через feature multi_agent_v2. V2 использует именованное дерево задач (/root/research/parser) вместо основной адресации по UUID и меняет семантику передачи истории и межагентного общения.

spawn_agent (agent_tool.rs:53-87)

Параметр	Тип	Описание
`task_name`	string	Обязательное имя задачи из lowercase letters, digits и underscores; формирует канонический путь агента
`message`	string	Обязательное начальное текстовое задание
`agent_type`	string?	Опциональная роль; несовместима с full-history fork
`fork_turns`	string?	`none`, `all` или положительное число последних turns; отсутствие поля означает `all`

Возвращает канонический task_name и, если metadata не скрыты, опциональный nickname. Параметр v1 fork_context в v2 отклоняется с ошибкой. Parallel calls: ✗.

send_message (agent_tool.rs:123-152) — ставит сообщение в mailbox агента, но не запускает новый turn. Параметры: target, message.

followup_task — отправляет следующую задачу и запускает turn свободного агента; если агент занят, задача выполнится после текущего turn. Handler: FollowupTaskV2.

wait_agent — ждёт любое обновление mailbox, а не финальный статус конкретного списка UUID. Принимает опциональный timeout_ms; содержимое сообщения отдельно доставляется родителю. Handler: WaitAgentV2.

close_agent — завершает агента, адресованного по относительному или каноническому task path, и его открытых потомков. Handler: CloseAgentV2.

list_agents — перечисляет живых агентов текущего дерева, опционально ограничивая результат через path_prefix. Handler: ListAgentsV2.

5. Пакетная обработка (Agent Jobs)

Запуск одного и того же агента над CSV-строками с параллелизмом — для batch-задач (массовая обработка тикетов, миграция кода в N файлах, и т.п.).

`spawn_agents_on_csv`

Файл: tools/src/agent_job_tool.rs:6-63.

Параметр	Тип	Описание
`csv_path`	string	Путь к входному CSV
`instruction`	string	Шаблон с `{column_name}` плейсхолдерами
`id_column`	string	Колонка-идентификатор
`output_csv_path`	string	Куда писать результаты
`max_concurrency`	int	Сколько workers параллельно
`max_runtime_seconds`	int	Глобальный timeout

Блокирующий вызов — возвращается только когда все workers завершились.

`report_agent_job_result`

Файл: tools/src/agent_job_tool.rs:66-100.

Worker-only tool: внутри sub-agent'а вызывается с job_id, item_id, result, stop, чтобы записать строку в output_csv_path. Parent его не вызывает.

6. Планирование и цели

`update_plan`

Файл: tools/src/plan_tool.rs:6-49.

Обновление checklist плана задачи и прогресса в UI. Это не переключатель collaboration mode. Handler явно отклоняет update_plan в Plan mode; там план формируется разговором и итоговым <proposed_plan>, а tool используется в обычных execution-turns.

Параметр	Тип	Описание
`explanation`	string	Краткое описание изменения плана
`plan`	array of `{ step: string, status: enum }`	Шаги

Статусы: pending, in_progress, completed. Parallel: ✗.

`get_goal` / `create_goal` / `update_goal`

Файл: tools/src/goal_tool.rs.

Управление долгоиграющей целью треда (см. 13-goal-and-modes.md):

get_goal — вернуть текущую цель (если есть).
create_goal — параметры objective (текст), token_budget (опционально, в токенах).
update_goal — status: complete | blocked. Только эти два перехода доступны модели (paused/cleared только через UI).

Parallel: ✗.

7. Запросы к пользователю

`request_user_input`

Файл: tools/src/request_user_input_tool.rs:11-84.

Запрос интерактивного решения у пользователя — TUI рендерит inline-форму с вариантами.

Параметр	Тип	Описание
`questions`	array of `{ id, header, question, options }`	Список вопросов

Возвращает массив ответов. Используется, когда модель упирается в неоднозначность и просит уточнить.

`request_permissions`

Расположение: local_tool.rs:create_request_permissions_tool.

Явный запрос на расширение sandbox-разрешений в текущей сессии. Не обязателен — обычно модель просто пробует команду и реагирует на approval-диалог.

8. MCP (Model Context Protocol)

См. также 06-mcp.md.

`list_mcp_resources`

Файл: tools/src/mcp_resource_tool.rs:6-32.

Параметры: server (id), cursor (для пагинации). Возвращает список ресурсов.

`list_mcp_resource_templates`

Файл: tools/src/mcp_resource_tool.rs:34-60.

То же, но для параметризованных ресурсов (с placeholder'ами в URI).

`read_mcp_resource`

Файл: tools/src/mcp_resource_tool.rs:62-94.

Параметры: server, uri. Возвращает содержимое ресурса (text/json/blob).

Динамические MCP tools

Каждый MCP-сервер регистрирует свои функции — они автоматически попадают в реестр как Namespace { name: "<server_id>", tools: [...] }. См. tools/src/mcp_tool.rs:6-36. Handler — ToolHandlerKind::Mcp.

9. Вспомогательные

`search_in_files`

Файл: tools/src/utility_tool.rs:94-158.

Полнотекстовый поиск по содержимому файлов под директорией (с учётом .gitignore). Возвращает path:line: text. Предпочтительнее grep/rg/git grep — не требует внешних утилит и не шеллит.

Параметр	Тип	Описание
`query`	string	Текст (или regex, если `regex=true`)
`path`	string?	Директория поиска (по умолчанию — cwd)
`glob`	string?	Ограничение по файлам (`.rs`, `src//.py`)
`regex`	bool?	Трактовать `query` как regex (linear-time, ReDoS-safe)
`context_lines`	int?	Контекст вокруг совпадения (0-3)
`max_results`	int?	Лимит совпадений (макс. 200)

Handler: SearchInFiles. Parallel: ✓.

`astracode_help`

Файл: tools/src/utility_tool.rs:42-61.

Возвращает авторитетную справку по использованию AstraCode (slash-команды, режимы, лицензия). Используется моделью, когда пользователь спрашивает, как работать с AstraCode. Handler: AstraCodeHelp. Parallel: ✓.

`list_dir`

Файл: tools/src/utility_tool.rs:6-40.

Перечисление содержимого директории.

Параметр	Тип	Описание
`dir_path`	string	Абсолютный путь к директории
`offset`	int?	1-indexed смещение
`limit`	int?	Сколько записей вернуть
`depth`	int?	Глубина обхода, целое число не меньше 1

Parallel: ✓.

`view_image`

Файл: tools/src/view_image.rs:14-36.

Подгрузить локальное изображение в контекст модели (если она multi-modal).

Параметр	Тип	Описание
`path`	string	Путь к файлу
`detail`	enum `original`?	Опционально запросить исходное разрешение; отсутствие поля использует обычный preview

Parallel: ✓.

`tool_suggest`

Файл: tools/src/tool_discovery.rs. Discovery-tool: возвращает список доступных tool'ов с описаниями. Используется агентом для «осмотреться, что я умею». Parallel: ✓.

10. Code Mode (встроенный интерпретатор JavaScript)

code-mode/ крейт — встроенный интерпретатор JavaScript (V8 isolate) для модели. Принимает raw JS-код (без Node, без FS, без сети), выполняет его как async-модуль. Полезен для вычислений, обработки данных, композиции tool-вызовов.

`exec`

Файл: tools/src/code_mode.rs:138 (create_code_mode_tool; create_wait_tool — на строке 93).

exec — freeform tool: на вход передаётся raw JavaScript, соответствующий Lark grammar, а не JSON-объект { "code": ... }. Скрипт выполняется как async module и может вызывать доступные nested tools через объект tools.

Возвращает stdout/stderr/result. Parallel: ✗.

`wait`

Ожидает завершение ранее yielded cell. Это отдельный function tool с полями cell_id, опциональными yield_time_ms и max_tokens. Handler: CodeModeWait.

11. Тестовые / служебные

`test_sync_tool`

Файл: tools/src/utility_tool.rs:152 (create_test_sync_tool; create_astracode_help_tool — на строке 42).

Для интеграционных тестов: позволяет синхронизировать параллельные tool-вызовы через barrier.

Параметр	Тип	Описание
`sleep_before_ms`	int	Задержка до barrier
`sleep_after_ms`	int	Задержка после
`barrier`	`{ id, participants, timeout_ms }`	Барьер

Не используется моделью в продакшене — только в тестах LLM-режимов.

Dynamic tools

DynamicToolSpec (dynamic_tool.rs:5-13) — runtime-зарегистрированные tools (например, от плагинов). Handler: DynamicTool.

Deferred tools — отложенная загрузка: схема tool'а отправляется модели только по запросу (ToolSearch в Claude), чтобы не раздувать system prompt. См. 19-agent-loop.md.

12. Поведение в sandbox и approval

Каждый tool маршрутизируется через permission_profile:

Tool	Read FS	Write FS	Shell	Network	Approval по умолчанию
`exec_command` / `shell`	✓	✓ (по writable_roots)	✓	по `network_access`	`on-failure`
`apply_patch`	✓	✓ (workspace)	✗	✗	`on-failure`
`list_dir`, `view_image`	✓	✗	✗	✗	`never`
`spawn_agent`, `update_plan`, `_goal`	—	—	—	—	`never` (внутренние)
MCP tools	по `approval_mode` сервера	—	—	—	`auto`/`prompt`/`approve`
`exec` (code mode)	через вызванные nested tools	через вызванные nested tools	JS внутри V8	напрямую нет	определяется каждым nested tool
`request_user_input`	—	—	—	—	сам по себе диалог

Approval-диалоги — см. 09-security.md.

13. Что НЕ tool

В отличие от инструментов, скиллы — это markdown-инструкции, которые подгружаются в контекст; они не имеют JSON-schema, не вызываются как функции. Скилл может использовать tools (например, skill-installer использует exec_command для git clone). См. 05-skills.md.

Хуки — это lifecycle event-listeners, а не сами tools. PreToolUse и PostToolUse покрывают только handlers, которые формируют hook-payload, и PostToolUse вызывается только после успешного результата. См. 08-hooks.md.

14. Как добавить свой tool

См. подробный recipe в 22-cookbook.md.

1. Архитектура

Типы спецификаций

Реестр и handlers

Sandbox и approvals

2. Выполнение команд

exec_command

write_stdin

shell (legacy)

shell_command

3. Редактирование файлов

apply_patch

write_file

4. Multi-agent (v1 и v2)

v1 API (основной)

v2 API (экспериментальный, по умолчанию выключен)

5. Пакетная обработка (Agent Jobs)

spawn_agents_on_csv

report_agent_job_result

6. Планирование и цели

update_plan

get_goal / create_goal / update_goal