# Agent Switcher

Cambio de agentes estilo **opencode** para pi: alterna entre agentes (p. ej.
`planner` y `build`) y cada agente aplica **su propio modelo**, nivel de
thinking, allowlist de herramientas, rol de solo lectura y system prompt.

## Instalación

- Instalación permanente:
  `pi install https://git.sargatxet.cloud/sargatxet/pi-agent-switcher`
- Una sola sesión:
  `pi -e https://git.sargatxet.cloud/sargatxet/pi-agent-switcher`
- Manual (fallback):
  `git clone https://git.sargatxet.cloud/sargatxet/pi-agent-switcher.git ~/.pi/agent/extensions/agent-switcher`
  o probar sin instalar:
  `pi --extension <ruta-del-repo>/extensions/agent-switcher/index.ts`

## Comandos

| Comando / atajo | Acción |
|---|---|
| `/agent` | Selector de agentes (lista si no hay TUI) |
| `/agent <nombre>` | Cambiar al agente `<nombre>` (también alias) |
| `/agents` | Listar agentes con su estado y modelo |
| `/agent model` | Modelo efectivo del agente activo |
| `/agent model <ref>` | Fijar el modelo del agente activo **para esta sesión** |
| `/agent model reset` | Quitar el override y volver al `model:` del archivo |
| `F5` / `F6` | Cambiar al agente planner/build (configurable con `shortcut:`) |
| `pi --agent planner` | Arrancar con un agente concreto |

El agente activo se confirma con el aviso `Agente activo: … · modelo …` al
cambiar, y con `/agent list`. La línea de estado del footer se eliminó por
resultar confusa.

## Definir agentes

Cada agente es un Markdown con frontmatter en:

- `~/.pi/agent/agents/*.md` — agentes de usuario
- `<proyecto>/.pi/agents/*.md` — agentes de proyecto (sobrescriben al mismo nombre)

Ejemplo (`~/.pi/agent/agents/build.md`):

```markdown
---
name: build
description: Implementation agent running on the fast model
aliases: constructor, implement
advertise: true
model: provider/model-id
thinking: medium
systemPromptMode: append
inheritProjectContext: true
inheritSkills: true
---

You are `build`: the implementation agent. ...
```

### Claves del frontmatter

| Clave | Defecto | Significado |
|---|---|---|
| `name` | nombre del archivo | Identificador único para `/agent <nombre>` |
| `description` | — | Texto mostrado en el selector |
| `aliases` | — | Nombres alternativos, separados por comas |
| `advertise` | `true` | `false` = oculto en el selector y en el ciclo |
| `shortcut` | — | Atajos directos al agente, separados por comas (p. ej. `f5`). Conflicto con atajos nativos: pi lo descarta con aviso |
| `model` | — | `provider/id` o un `id` único. **Sin valor = conserva el modelo actual** |
| `thinking` | — | `off\|minimal\|low\|medium\|high\|xhigh\|max` |
| `systemPromptMode` | `append` | `replace` = el cuerpo sustituye el prefijo del prompt; `append` = se añade |
| `inheritProjectContext` | `true` | `false` = el agente no ve `AGENTS.md`/archivos de contexto |
| `inheritSkills` | `true` | `false` = el agente no ve las skills |
| `tools` | — | Allowlist de herramientas activas (separadas por comas o espacios) |
| `acceptanceRole` | — | `read-only` = bloquea `edit`/`write` y restringe `bash` a comandos de solo lectura |
| `defaultContext` | — | Aceptado e ignorado (fresco no aplica al cambio inline) |

El cuerpo del archivo (tras el frontmatter) es el system prompt del agente.

## Semántica (equivalente a opencode)

- **El agente activo gobierna**: su `model` y `thinking` se aplican al
  activarse y se reafirman en cada `before_agent_start`; su `tools` y su
  prompt también se aplican cada run (todo idempotente).
- **Agente sin `model`** = no toca el modelo: conserva el de la sesión
  (útil para un `build` que simplemente hereda el modelo por defecto de pi).
- **Overrides de sesión**: solo `/agent model <ref>` crea un override para el
  agente activo y se restaura al volver a él. Los cambios con `/model` o
  `Ctrl+P` aplican de inmediato, pero **el modelo del agente se reafirma en
  cada prompt** (los eventos de modelo ya no se autograban: así los cambios
  de otras extensiones no pueden intercambiar los modelos de los agentes).
  El override lleva memoria del valor del archivo que tenía al crearse:
  **si editas `model:` en el `.md`, el archivo manda** y el override se
  descarta. `/agent model reset` lo borra a mano; `/agent list`
  marca los agentes con modelo «(sesión)». Para fijarlo de forma permanente,
  edita el `model:` del archivo del agente.
- **Persistencia**: el agente activo y los overrides se guardan en la
  sesión y se restauran al reanudarla.
- **Solo lectura**: además de desactivar las herramientas de escritura,
  hay una segunda barrera en `tool_call` que bloquea `edit`/`write` y
  cualquier comando bash que no esté en la lista de solo lectura
  (`policy.ts`).

## Notas

- Los agentes se recargan en cada inicio de sesión; tras editar un `.md`
  durante la sesión usa `/reload` (también recarga los atajos nuevos).

## Los atajos de teclado no funcionan

1. **¿La sesión cargó la extensión?** Ejecuta `/hotkeys`: debe aparecer
   `Cambiar al agente …`. Si no aparece, ejecuta `/reload` (o reinicia pi):
   las sesiones abiertas antes de instalar el plugin no lo cargan solas.
2. **¿El terminal entrega la combinación?** La configuración por defecto usa
   **teclas de función** (`f5`, `f6`) precisamente porque llegan en todos los
   terminales. Si cambias a combinaciones como `ctrl+alt+x`, estas solo llegan
   a pi si el terminal usa el protocolo kitty/CSI-u (kitty, Ghostty, WezTerm
   con `enable_kitty_keyboard`, VS Code ≥ 1.109.5) o si envía `ESC + carácter
   de control`; fallan en terminales clásicas, dentro de tmux y con teclado
   español donde **AltGr = Ctrl+Alt**.
3. En tmux, habilita `set -s extended-keys on` para que lleguen las teclas
   modificadas (ver la doc de pi sobre tmux).
4. Cambia las teclas editando `shortcut:` en el `.md` del agente y
   ejecutando `/reload`. Cualquier combinación que aparezca en `/hotkeys`
   es válida.
- Si otra extensión también llama a `setModel` en `before_agent_start`
  (p. ej. un cambio de modelo automático por fases), las dos competirán
  en cada run: mantén solo una estrategia activa.
- Con **pi-subagents** instalado, `subagents_enable` se fuerza siempre en
  las herramientas activas. En agentes con `tools:`/`read-only` esa
  llamada se bloquea en `tool_call` (delegar permitiría escribir ficheros);
  el resto de su comportamiento no se ve afectado.
- Para probar sin instalar nada: `pi --extension <ruta-del-repo>/extensions/agent-switcher/index.ts`.