## Invocación de LLM: SIEMPRE `ask_llm`, NUNCA `claude -p`

**REGLA DURA.** Para ejecutar un modelo LLM desde cualquier código del ecosistema (scripts, heredocs, apps, pipelines, agentes), usa el grupo `claude-direct` — empezando por `ask_llm_py_core`. **NUNCA** uses `claude -p` ni lances el binario `claude` como subproceso para obtener una respuesta del modelo.

### Por qué

| | `claude -p` | `ask_llm` / `claude-direct` |
|---|---|---|
| Mecanismo | Lanza Claude Code entero (proceso `claude`) | Habla directo a `api.anthropic.com/v1/messages` |
| Arranque | ~7-15s (carga MCP + `CLAUDE.md` ~100k tokens) | **0 — request HTTP directa** |
| Latencia/msg | ~9-15s | **~2.5s** |
| Coste | Alto (re-carga contexto cada vez) | Mínimo (solo tu prompt) |
| Tools | Las de Claude Code (no controlables) | **Las que tú defines** (`run_claude_tool_loop`) |
| Streaming | indirecto | nativo (`stream_anthropic_messages`) |

`claude -p` es lento, caro y arranca todo Claude Code para una completion. `ask_llm` es la API directa: arranque 0, rápido, con tus propias tools. Usa el token OAuth que Claude Code ya guarda en `~/.claude/.credentials.json`.

### Cómo (según el caso)

| Caso | Usa |
|---|---|
| Pregunta/chat one-shot | `fn run ask_llm "..."` o `from core.ask_llm import ask_llm` |
| Streaming de eventos crudos (text/tool_use deltas) | `stream_anthropic_messages_py_core` |
| Agente con TUS tools (tool-use loop) | `run_claude_tool_loop_py_core` (defines `tools` + `dispatch`) |
| Token OAuth | `load_claude_oauth_token_py_core` (automático dentro de las anteriores) |
| Distribuir fuera del registry | `apps/llm_cli/llm.py` (versión standalone autocontenida) |

```python
import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from core.ask_llm import ask_llm
respuesta = ask_llm("resume esto en 3 lineas: ...", model="claude-haiku-4-5-20251001", echo=False)
```

### Legacy

`claude_stream_go_core` (lanza `claude -p --output-format stream-json`) es el **camino antiguo**. No usarlo en código nuevo — preferir las funciones `claude-direct`. Queda solo para compatibilidad de consumidores existentes.

### Excepción acotada

Si una tarea necesita **genuinamente las capacidades de Claude Code** (sus tools nativas, los MCP del repo, plan mode, el contexto del proyecto) y no basta con el modelo + tus propias tools via `run_claude_tool_loop`, entonces NO es una "invocación LLM" simple: documenta por qué en el código. El **default sin excepción es `ask_llm`**.

### Telemetría / auditoría

Un `claude -p` o un `subprocess(["claude", "-p", ...])` en código nuevo es un antipatrón auditable: sustituir por `ask_llm` / `claude-direct`. Buscar usos: `grep -rn 'claude -p' --include='*.py' --include='*.sh' --include='*.go'`.

### Relación con otras reglas

- [[registry_calls]] — patrones canónicos de invocación de funciones; esta regla fija el patrón para la sub-tarea "invocar un LLM".
- [[registry_first]] — reusar antes que reescribir; `ask_llm` es la función reutilizable para LLM.