Инструменты

Жизненный цикл tool call

sequenceDiagram
    participant A as Agent
    participant Bus
    participant TUI
    participant T as Tool

    A->>Bus: ToolCall{id, name, args}
    Bus->>TUI: ToolCallMsg
    Note over TUI: карточка инструмента в чате

    alt Требует approval (не YOLO)
        A->>Bus: ToolApprovalRequest{corrID, name, args}
        Bus->>TUI: ApprovalRequestMsg
        TUI->>TUI: очередь аппрувов
        TUI->>Bus: ToolApprovalResponse{corrID, approved, scope}
        Bus->>A: ответ
    end

    alt Долгая операция (terminal)
        A->>Bus: ToolStatus{running}
        T->>Bus: TerminalNewRunning{cmd}
        Bus->>TUI: TerminalNewRunningMsg
        loop Вывод
            T->>Bus: TerminalAppendString{delta}
            Bus->>TUI: TerminalAppendStringMsg
        end
        T->>Bus: TerminalCompleted{exitCode}
    end

    T-->>A: Result
    A->>Bus: ToolResult{id, name, display}
    Bus->>TUI: ToolResultMsg
    Note over TUI: карточка → done с результатом

События

ToolCallEvent {sessionID, toolCallID, name, args, display}

Карточка инструмента появляется в чате. display — человекочитаемое описание ("read path: foo.go").

ToolResultEvent {sessionID, toolCallID, toolName, display, isError}

Результат выполнения инструмента. Карточка помечается как done.

ToolStatusEvent {sessionID, toolCallID, toolName, status, timeoutSec}

Изменение состояния: pending → running → done / error.

ToolApprovalRequestEvent {sessionID, correlationID, toolName, args, subagentSessionID, serverName}

Запрос подтверждения пользователя. Блокирует выполнение инструмента до ответа.

subagentSessionID — если запрос от сабагента, relay переотправляет с parentSessionID чтобы TUI увидел его.

ToolApprovalResponseEvent {correlationID, approved, scope}

Ответ пользователя. scope определяет длительность решения:

Терминал

TerminalNewRunningEvent {sessionID, toolCallID, command, description}

Команда запущена. TUI открывает окно терминала в сайдбаре.

TerminalAppendStringEvent {sessionID, toolCallID, delta}

Инкрементальный вывод команды. Текст накапливается в окне терминала.

TerminalCompletedEvent {sessionID, toolCallID, exitCode, isError}

Команда завершена. Окно терминала помечается как done.

Все три публикуются в TopicTerminalStream.