# agents

## Назначение

`agents` сейчас отключен по умолчанию и не запускает subagents. Extension оставлен как переходная поверхность для будущего порта OMP `task`: он умеет перечитать markdown definitions и показать их через `/agent list`, но любые попытки выполнить задачу через `task`, `runAgent` или `/agent run` завершаются `isError=true`.

## Почему он есть в проекте

Нужный продуктовый behavior уже есть в OMP `TaskTool`: discovery агентов, child sessions, progress, artifacts, `agent://` outputs, async jobs, isolation и tool restrictions. В `miloc-pi` мы не делегируем выполнение наружу, а должны забрать эту функциональность и оформить здесь как наш plugin/API surface. До этого локальный deterministic accepted-task summary был опасен тем, что выглядел как успешный запуск агента, хотя модель и subprocess реально не создавались.

## Пользовательская поверхность

- Пользователь вызывает `/agent list`, чтобы увидеть загруженные markdown definitions в виджете `agents`.
- Пользователь может вызвать `/agent run <name> <task>`, но команда покажет fail-closed сообщение о том, что OMP `task` backend еще не портирован.
- Агент может вызвать primary tool `task` с OMP-shaped параметрами `agent`, `tasks`, optional `context`, `schema`, `isolated`; результат будет `isError=true` до порта OMP `TaskTool`.
- Старый tool `runAgent` оставлен как legacy alias, но он тоже fail-closed и больше не возвращает synthetic success.

## Как работает по коду

Entrypoint регистрирует команду `agent`, primary tool `task` и legacy tool `runAgent`. Перед command/tool вызовами extension обновляет список definitions из bundled `agents/*.md`, project `.pi/agents` и `.agents/agents`. Parser принимает только простой frontmatter: `name`, `description`, `allowedTools` или `tools`, `risk`, `readOnly` и optional `modelOverride`.

Execution path намеренно отсутствует. Функция `taskNotPorted` проверяет, что запрошенные agent names существуют в `sharedState.agents`, и затем возвращает ошибку с source evidence для OMP `task` files. Это защищает API от фейкового выполнения до настоящего порта.

- Entrypoint: `./extensions/agents/index.ts`
- Manifest: `extensions/agents/manifest.json`
- Commands: `agent`
- Tools: `task`, `runAgent`
- Hooks: none
- Permissions: fs.read=none, fs.write=none, subprocess=none, network=none, browser=false, models=false, ui=`setWidget`, `notify`
- State: список agent definitions живет в `sharedState.agents` только в памяти; источником остаются markdown-файлы.
- Review: status=reviewed, source=wrapper-first, reviewedBy=pi-dev-extensions, reviewedAt=2026-06-01, risk=high

## Ограничения и риски

Этот extension пока не выполняет задачи, не создает child sessions, не пишет artifacts, не поддерживает async delivery и не применяет isolation. Он полезен только как disabled contract shell и как список локальных definitions. Включать его по умолчанию нельзя, пока OMP `TaskTool` не портирован и не проверен в Pi runtime.

## Решение

Решение: `OMP-port-backlog`. Следующий шаг — портировать или тонко упаковать OMP `task` backend. Miloc-specific mapping для markdown agent definitions можно оставить только если он будет совместим с OMP discovery и не станет второй системой запуска агентов.