# Plan: Herramientas para los bots

## Objetivo
Permitir que los bots ejecuten herramientas reales (funciones Go) como respuesta a
decisiones del LLM — patrón function calling / tool use.

## Estado: COMPLETADO

---

## Diseño

### Capa pura (`pkg/tools/`)
- Definir `ToolSpec` con nombre, descripción y esquema JSON de parámetros
- Definir `ToolCallAction` en `pkg/decision/` — acción pura que contiene
  `ToolName string` y `Args map[string]any`
- El motor de reglas puede emitir `ToolCallAction` como cualquier otra acción

### Capa shell (`shell/tools/`)
- `Executor` que mapea nombre → función Go real
- Ejecuta la herramienta y devuelve `ToolResult{Output string, Err error}`
- El Runner de `shell/effects/` llama al Executor cuando recibe `ToolCallAction`

### Integración LLM
- `shell/llm/anthropic.go` y `openai.go` ya soportan tool_use / function_calling
- Mapear `[]ToolSpec` al formato nativo de cada proveedor
- Parsear la respuesta del LLM para extraer llamadas a herramientas

### Herramientas iniciales a implementar
| Herramienta     | Descripción                         | Shell             |
|-----------------|-------------------------------------|-------------------|
| `http_get`      | GET a una URL, devuelve body        | `shell/tools/`    |
| `http_post`     | POST JSON a una URL                 | `shell/tools/`    |
| `ssh_command`   | Ejecutar comando remoto por SSH     | `shell/ssh/`      |
| `read_file`     | Leer archivo local                  | `shell/tools/`    |
| `matrix_send`   | Enviar mensaje a una sala Matrix    | `shell/matrix/`   |

---

## Archivos a crear/modificar
- `pkg/tools/spec.go` — ToolSpec, ToolResult
- `pkg/decision/actions.go` — añadir ToolCallAction
- `shell/tools/executor.go` — registro y ejecución de herramientas
- `shell/effects/runner.go` — manejar ToolCallAction
- `shell/llm/anthropic.go` — emitir tools en el request, parsear tool_use blocks
- `shell/llm/openai.go` — idem para function_calling
- `agents/<id>/agent.go` — registrar herramientas por agente

## Notas
- Las herramientas se declaran en `pkg/` (pure spec) pero se implementan en `shell/`
- Un agente solo tiene acceso a las herramientas declaradas en su config
- Respetar `security.allowed_tools` del config YAML