MODULE_02 · УРОК 2.3

Шлюз подтверждения

В create_bash_tool сейчас прошит один единственный закон: нет в белом списке - значит стоп. Дома за клавиатурой это правильно, а вот в CI такой агент встанет намертво, потому что нажать «ОК» там некому. Субагенту, наоборот, вся ваша власть ни к чему: пусть ходит по короткому поводку. Получается, политика зависит от того, кто и где запускает агента, и держать её внутри инструмента больше нельзя. Сегодня вынесем решение в отдельный approval.py, подключим его в tools_bash.py и научимся переключать три режима одной строкой в main.py.

ЧТО ПОЛУЧИТСЯ Файл approval.py + правка tools_bash.py + пара строк в main.py. Меняете {"mode": "interactive"} на "background" или "delegated" - и та же команда то проходит, то блокируется.

Слова, которые встретятся

  • needs_approval(command) - функция, которая отвечает на один вопрос: нужно ли для этой команды разрешение человека. True означает «не запускай, верни текст блокировки», False - «можно смело отдавать в subprocess».
  • Режим (mode) - настройка, по которой эта функция принимает решение. У нас их три: дома за клавиатурой, в CI без человека и для субагента с урезанными правами.

Быстрый путь

  1. Создать approval.py.
  2. В tools_bash.py заменить аргумент safe_prefixes на needs_approval.
  3. В main.py собрать create_approval(...) → create_bash_tool(...).
  4. Прогнать две команды в разных режимах.

Какие файлы трогаем

Файл Что делать
approval.py Создать. Типы конфига + create_approval + список SAFE_PREFIXES.
tools_bash.py Править. Сигнатура фабрики: вместо списка префиксов - функция needs_approval.
main.py Править. Импорты, вызов create_approval, передать результат в create_bash_tool.
local_bash.py Не трогать. Он по-прежнему только крутит subprocess.

Шаг 1. Создайте approval.py

Новый файл кладём рядом с main.py. Внутри только белый список и решение «блокировать или нет»: ни subprocess, ни агента, ни малейшего представления о том, кто эту политику будет применять. Такой файл потом приятно читать и легко тестировать.

approval.py (целиком)

from collections.abc import Callable
from typing import Literal, TypedDict

class InteractiveConfig(TypedDict):
    mode: Literal["interactive"]

class BackgroundConfig(TypedDict):
    mode: Literal["background"]

class DelegatedConfig(TypedDict):
    mode: Literal["delegated"]
    trust: list[str]

ApprovalConfig = InteractiveConfig | BackgroundConfig | DelegatedConfig

# Общий белый список для режима interactive (дома за клавиатурой)
SAFE_PREFIXES = [
    "ls", "cat", "echo", "pwd", "which", "find",
    "head", "tail", "wc",
    "git log", "git status", "git diff",
]


def create_approval(config: ApprovalConfig) -> Callable[[str], bool]:
    """Вернуть функцию needs_approval(command) -> bool."""

    def needs_approval(command: str) -> bool:
        cmd = command.strip()

        # CI: человека нет - пускаем всё (осознанный риск)
        if config["mode"] == "background":
            return False

        # Субагент: только то, что дали в trust
        if config["mode"] == "delegated":
            allowed = config["trust"]
            return not any(cmd.startswith(p) for p in allowed)

        # interactive: как старый белый список
        return not any(cmd.startswith(p) for p in SAFE_PREFIXES)

    return needs_approval

Если продраться через типы, вся суть файла сводится к трём строчкам поведения:

  • interactive - можно то, что в SAFE_PREFIXES; остальное блок.
  • background - можно всё (для CI).
  • delegated - можно только строки из trust.

Шаг 2. Поправьте tools_bash.py

Политика написана, но пока никто её не спрашивает. После урока 2.2 в фабрике у вас примерно такая картина:

def create_bash_tool(
    operations: BashOperations,
    safe_prefixes: list[str],
) -> Callable[..., str]:
    def is_safe(command: str) -> bool:
        ...
    async def bash(command: str) -> str:
        if not is_safe(command):
            return "Заблокировано..."
        ...

Меняем немного: второй аргумент теперь не список, а готовая функция из approval.py. Фабрика перестаёт разбираться в префиксах самостоятельно и просто спрашивает у политики разрешения:

tools_bash.py - новая сигнатура фабрики

from collections.abc import Callable

# ExecResult, BashOperations - как были в уроке 2.2

def create_bash_tool(
    operations: BashOperations,
    needs_approval: Callable[[str], bool],  # было: safe_prefixes: list[str]
) -> Callable[..., str]:

    async def bash(command: str) -> str:
        """Выполнить shell-команду в рабочей директории.
        ... ваш полный docstring из 2.1 ...
        """
        if needs_approval(command):
            return (
                f'Заблокировано: "{command}" требует подтверждения '
                f"(режим политики в main.py)."
            )
        result = await operations.exec(command)
        return result["stdout"] or "(нет вывода)"

    return bash
СЛОМАЕТСЯ СТАРЫЙ ВЫЗОВ Как только вы поменяли сигнатуру, строка create_bash_tool(local_ops, SAFE_PREFIXES) в main.py стала невалидной: там ждут функцию, а вы отдаёте список. В лучшем случае получите TypeError, в худшем - молчаливо странное поведение. Так что шаг 3 делайте сразу, не откладывая.

Шаг 3. Соберите всё в main.py

Найдите место, где вы делали create_bash_tool(local_ops, SAFE_PREFIXES), и замените на:

main.py - фрагмент

from local_bash import LocalBashOps
from tools_bash import create_bash_tool
from approval import create_approval
from pydantic_ai import Agent, Tool

# ... cwd как раньше ...

local_ops = LocalBashOps(cwd)

# Переключайте ТОЛЬКО эту строку, чтобы менять поведение:
needs_approval = create_approval({"mode": "interactive"})
# needs_approval = create_approval({"mode": "background"})
# needs_approval = create_approval({
#     "mode": "delegated",
#     "trust": ["pwd", "find", "git status"],
# })

bash_fn = create_bash_tool(local_ops, needs_approval)

agent = Agent(
    "deepseek:deepseek-chat",
    deps_type=Path,
    # Один способ зарегистрировать bash - через tools=[...]
    tools=[Tool(bash_fn, takes_ctx=False)],
    instructions=...,
)

# read / grep - как раньше, через @agent.tool ниже
# НЕ вызывайте ещё и agent.tool_plain(bash_fn): будет конфликт имени 'bash'
tools=[...] ИЛИ tool_plain - НЕ ОБА Зарегистрировать функцию из фабрики можно так: tools=[Tool(bash_fn, takes_ctx=False)] при создании Agent, или позже agent.tool_plain(bash_fn). Достаточно одного варианта. Если уже есть tools=[Tool(bash_fn, ...)], строка agent.tool_plain(bash_fn) не нужна - иначе снова Tool name conflicts: 'bash'.

И приберитесь за собой: SAFE_PREFIXES вместе со старой функцией is_safe из main.py нужно удалить. Список переехал в approval.py, а is_safe теперь вообще никто не вызывает. Оставите - и через неделю будете гадать, какая же из двух копий белого списка работает.

ЗАЧЕМ ВООБЩЕ ОТДЕЛЬНЫЙ ФАЙЛ Ради одной строчки-словаря в main.py: поведение агента меняется ею целиком, без трёх почти одинаковых функций по копипасте. А когда позже захочется читать эту настройку из конфига или выдавать субагенту его собственную, код политики уже будет готов и проверен.

Проверьте

Самое приятное в этом уроке - проверка: политику видно сразу, без погружения в код. Оставьте mode: "interactive" и выполните:

uv run python main.py . "Выполни: git status"
uv run python main.py . "Выполни: pip install requests"

Первая команда пройдёт, её префикс есть в SAFE_PREFIXES. Вторая вернёт текст блокировки, и никакой пакет никуда не установится.

Теперь фокус. Закомментируйте interactive, раскомментируйте background и повторите pip install requests: тот же агент, тот же инструмент, а шлюз пропускает. Если команда после этого сама свалится с ошибкой, к политике это уже не имеет отношения.

Осталось попробовать delegated с trust: ["git status"], и картина станет полной: git status проходит, pip install requests блокируется. Три разных мира, одна строка разницы.

ОДОБРИЛИ ≠ УСПЕХ КОМАНДЫ Шлюз сказал «можно», а pytest всё равно красный? Значит упали тесты, а не политика: пропустить команду и выполнить её удачно - это два независимых события. Смотрите на exit_code отдельно от решения шлюза, иначе будете чинить не то.

Готово, если:

  • Есть файл approval.py с create_approval
  • В tools_bash.py фабрика принимает needs_approval, а не список префиксов
  • В main.py bash собран через create_approval + create_bash_tool
  • В interactive: git status проходит, pip install - блок
  • Переключение на background / delegated меняет поведение без правки фабрики
НА ПОТОМ Пока «блок» - это просто строка, человека никто ни о чём не спрашивает. Настоящий диалог с вопросом «разрешить?» соберём в модуле 8, но идея останется прежней: если needs_approval вернул True, мы не молчим, а обязательно что-то отдаём модели.