Alcance del agente

El alcance del agente es la idea en el corazón de kovra: la frontera que permite a un agente de codificación de IA usar los secretos sin ver los sensibles.

Cuando se conecta kovra a Claude Code (o a cualquier cliente MCP), el agente no obtiene el vault. Obtiene un scope — una capacidad que dice exactamente qué puede direccionar y hacer esta sesión. Todo lo que el agente pide fluye a través de una única decisión de política en el core de kovra; el agente nunca toma esa decisión por sí mismo.

El scope se impone primero

Una coordenada fuera del scope de la sesión es indireccionable — no existe para ese canal. kovra no resuelve el secreto y luego lo niega; el secreto simplemente nunca aflora. Eso es defensa en profundidad: incluso un agente secuestrado o con prompt-injection no puede alcanzar lo que el scope excluye, porque esos secretos nunca estuvieron a su alcance para empezar.

El scope se define sobre ejes de operación

Crucialmente, el scope no es “nada de prod para el agente” — una prohibición de entorno tan tosca rompería flujos legítimos de diagnóstico y deploy. En cambio se define sobre tres ejes:

Operación — qué puede hacer el llamador con un valor:
metadata — list / status / fingerprint. No se toca ningún valor.
inject — entregar un valor a través de una operación hacia un proceso hijo; el valor nunca regresa al contexto del llamador.
reveal — devolver plaintext al contexto del llamador (el camino vigilado).
Filtros de proyecto / entorno — qué proyectos y entornos están en scope (ya sea cualquiera, o una allowlist explícita).

Cómo se establece ese scope depende del canal: kovra setup escribe el scope de un agente en el .mcp.json del proyecto (las claves KOVRA_MCP_ENVIRONMENTS / KOVRA_MCP_PROJECTS), mientras que el ssh-agent gobernado lee su propio scope desde un agent.toml en la raíz del vault. Ver Configuración para ambos.

La separación metadata / inject / reveal

Esta separación es por qué un agente puede ser útil y seguro al mismo tiempo:

Puede leer libremente metadatos — que un secreto existe, su coordenada, su sensibilidad — y razonar sobre el proyecto.
Puede inyectar secretos en los comandos que ejecuta a través del wrapper, de modo que el comando trabaje con el valor real — pero ese plaintext nunca aterriza en la ventana de contexto del modelo.
Puede revelar un valor a su contexto solo para el caso acotado que la política permite: un secreto no-prod y no-high que se haya marcado explícitamente como revealable. Los secretos high / prod / inject-only nunca son revelables al agente — sin excepción.

El origen importa para `prod`

kovra también rastrea quién inició una solicitud — agent o human. Pesa de manera distinta para el camino más riesgoso: traer plaintext de prod a un contexto se permite solo cuando un humano inicia un reveal deliberado en la CLI, nunca cuando lo pide un agente. La comodidad que obtiene un agente jamás se extiende a exfiltrar secretos de producción.

~/my-app % kovra setup
Vault ready; project `my-app`.
Updated .mcp.json (register the kovra MCP server).
Updated CLAUDE.md (insert/update the kovra conventions block).
Setup complete. Review CLAUDE.md and .mcp.json, then reload your agent to pick up the MCP server.

PS C:\my-app> kovra setup
Vault ready; project `my-app`.
Updated .mcp.json (register the kovra MCP server).
Updated CLAUDE.md (insert/update the kovra conventions block).
Setup complete. Review CLAUDE.md and .mcp.json, then reload your agent to pick up the MCP server.

Después de eso, el agente ve metadatos acotados y puede ejecutar comandos a través del wrapper. El plaintext de los secretos sensibles permanece en el vault, en la máquina, detrás de la política — exactamente donde uno todavía puede usarlo.