Capítulo 4 — Tools, permisos, approvals, hooks, secretos y trust boundaries¶
Un coding agent no se vuelve peligroso porque «tenga tools». El riesgo aparece cuando confundimos poder proponer una tool call con tener autoridad para producir el efecto que esa llamada intenta causar.
Un mismo modelo puede sugerir:
Read("src/auth.ts")
Bash("npm test")
Bash("npm publish")
GitHub.create_pull_request(...)
Cloud.delete_database(...)
Las cinco son acciones estructuralmente parecidas desde el punto de vista del modelo: nombre de tool + argumentos. Operativamente no tienen el mismo alcance, reversibilidad, credenciales ni blast radius.
El harness necesita una frontera explícita entre intención inferida y autoridad ejecutable.
La pregunta correcta no es «¿qué tools tiene el agente?»¶
Hay al menos seis planos distintos:
| Plano | Pregunta |
|---|---|
| Tool surface | ¿Qué acciones conoce el modelo y puede proponer? |
| Policy | ¿Qué clases de acciones están permitidas, bloqueadas o requieren revisión? |
| Approval | ¿Quién autorizó esta acción concreta, con qué alcance y durante cuánto tiempo? |
| Sandbox / runtime | ¿Qué filesystem, procesos y red puede alcanzar realmente la ejecución? |
| Identidad / secretos | ¿Con qué identidad se autentica y qué privilegios posee esa identidad? |
| Sistema remoto | ¿Qué ACL, branch protection, IAM o reglas propias aplica el destino? |
Una defensa seria compone esos planos. No sustituye cinco de ellos por un prompt que diga «ten cuidado».
Podemos expresarlo como un predicado conceptual:
Donde, para una acción \(a\):
- \(T\): la tool está disponible;
- \(P\): la policy permite la clase de acción;
- \(S\): la sandbox/runtime permite alcanzar el recurso;
- \(C\): la credencial presentada autoriza la operación;
- \(R\): el sistema remoto acepta la operación bajo sus propias reglas;
- \(A\): cualquier aprobación requerida sigue siendo válida para esa acción concreta.
No es una especificación de ningún producto. Es una forma útil de evitar una conclusión falsa: tool_available = true no implica authorized = true.
Tool availability y permission son controles diferentes¶
Reducir el catálogo de tools que ve el modelo tiene valor. Disminuye el espacio de acciones que puede proponer y evita intentos inútiles.
Pero ocultar una tool no es lo mismo que imponer una frontera de seguridad sobre la capacidad subyacente.
Un agente sin delete_file puede seguir borrando archivos si conserva un shell con suficiente autoridad. Un agente sin una tool HTTP dedicada puede seguir haciendo egress si puede ejecutar curl, Python, Node o un binario equivalente.
GitHub documenta esta separación explícitamente en Copilot CLI: --available-tools/--excluded-tools controlan qué tools puede elegir el modelo, mientras los permisos allow/deny controlan si puede ejecutarlas. La propia documentación recuerda que un shell autorizado puede instalar paquetes, borrar archivos, hacer push o abrir conexiones de red.6
La regla general es:
tool catalog = superficie de decisión del modelo
policy/runtime = superficie de autoridad del sistema
La primera ayuda al modelo. La segunda protege el sistema.
La policy debe vivir fuera de la inferencia del modelo¶
Una instrucción como esta puede orientar comportamiento:
Pero sigue siendo contexto que el modelo interpreta. Puede entrar en conflicto con otra instrucción, con contenido inyectado en el repositorio o simplemente con una clasificación errónea.
Una policy ejecutable debe evaluarse en una capa que no dependa de que el modelo recuerde obedecerla.
OpenAI describe precisamente esa separación en su despliegue interno de Codex: la sandbox define límites técnicos, la approval policy decide cuándo detenerse para pedir autorización, las network policies controlan destinos y las reglas pueden permitir, bloquear o exigir aprobación para patrones de comandos. Los requisitos administrados pueden imponerse de forma que el usuario no los sobrescriba.1
Claude Code también documenta que sus reglas de permisos son aplicadas por Claude Code, no por el modelo. Las instrucciones de prompt o CLAUDE.md pueden cambiar lo que Claude intenta hacer, pero no modifican las reglas allow/ask/deny del runtime.2
Eso sugiere una propiedad importante para un harness de producción:
Si el mismo contexto no confiable puede reescribir la policy que debería limitarlo, la frontera desaparece.
Deny, ask y allow no son tres niveles equivalentes¶
Un diseño útil distingue:
DENY → no existe una trayectoria autorizada para esta acción
ASK → existe una trayectoria, pero necesita autorización adicional
ALLOW → puede continuar sin una nueva intervención humana
ASK no significa «probablemente peligroso» y ALLOW no significa «demostrado seguro». Son decisiones de autoridad, no verificadores semánticos de corrección.
Por ejemplo:
Read(src/**) → ALLOW
Bash(npm test) → ALLOW
Bash(npm install *) → ASK
Bash(git push origin main) → DENY
Cloud(prod/*) → DENY
Estas reglas son ilustrativas, no una sintaxis portable entre harnesses.
La policy real debe razonar sobre más que el nombre superficial de la tool. El recurso, el entorno, los argumentos y la identidad importan.
Un approval debe estar ligado a la acción que el humano vio¶
El antipatrón más débil es:
La autorización obtenida es mucho más amplia que la decisión humana que probablemente se pretendía capturar.
Una aprobación robusta debería poder responder:
qué tool
qué argumentos normalizados
qué recurso o entorno
qué identidad/rol se utilizará
qué efecto esperado se mostró
qué scope temporal tiene
qué task/contract originó la acción
Para operaciones de alto impacto, el harness puede ligar la aprobación a un digest del request exacto:
approval_subject = H(
task_id,
tool,
normalized_arguments,
target_environment,
credential_identity,
policy_version
)
Este hash es un patrón de diseño, no un estándar. Su objetivo es impedir que una autorización a deploy staging se reutilice silenciosamente para deploy production, o que cambien los argumentos después de la revisión.
El problema TOCTOU también existe en agents¶
Time of check / time of use significa que el objeto revisado puede dejar de ser el objeto ejecutado.
Ejemplo:
1. agente propone: delete temp/cache-123
2. policy: ASK
3. humano revisa y aprueba
4. antes de ejecutar cambia el symlink temp/cache-123
5. la operación alcanza otro target
O a un nivel más agentic:
1. approval sobre tool=deploy, environment=staging, artifact=A
2. el plan continúa y recompila
3. artifact pasa a ser B
4. el deploy usa B con el approval de A
Por eso una aprobación no debería ser sólo un booleano. Debe tener sujeto, alcance, versión y expiración, y el runtime debe volver a validar sus precondiciones antes del efecto.
Sandbox y approvals resuelven preguntas distintas¶
Una sandbox puede responder:
¿puede este proceso escribir fuera del worktree?
¿puede abrir sockets?
¿puede leer ~/.ssh?
¿puede lanzar procesos hijos?
Un approval responde otra cosa:
OpenAI lo expresa de forma explícita para Codex: sandboxing y approvals trabajan juntos. La sandbox fija el límite técnico y la policy de aprobación decide cuándo una acción debe detenerse para revisión.1
Esto evita dos errores opuestos:
- «está en un container, así que puede usar cualquier credencial que tenga»;
- «el usuario hizo click en approve, así que ya no necesitamos limitar filesystem o red».
Ninguno es correcto.
Una credencial es autoridad empaquetada¶
Una API key, token OAuth, certificado o credential helper no es sólo «configuración para que funcione la tool». Define una identidad y delega privilegios.
La pregunta no es únicamente dónde guardar el secreto. También hay que decidir:
quién lo obtiene
para qué servicio
con qué scopes/roles
qué proceso lo recibe
cuánto dura
si puede heredarlo un subprocess
cómo se revoca
qué se registra sin filtrar el valor
OpenAI documenta en su despliegue de Codex el almacenamiento de credenciales CLI/MCP OAuth en el keyring del sistema y la asociación de autenticación al workspace administrado.1
GitHub, para Copilot cloud agent, separa igualmente el token por defecto —limitado al repositorio en el que se ejecuta— de los Agents secrets que un administrador puede añadir para acceder a recursos externos. También documenta que esos Agents secrets son distintos de los secrets de Actions, Codespaces y Dependabot.7
El detalle de cada producto cambia. La frontera conceptual permanece:
Preferir proyección mínima a «inyectar todos los secretos del entorno»¶
Supón que la tarea necesita descargar @acme/auth desde un registry privado.
Un diseño débil arranca el agente con:
Aunque la policy diga «sólo instala dependencias», cualquier proceso que pueda leer el environment hereda un conjunto de capacidades mucho mayor que la tarea.
Un diseño más estrecho proyecta sólo lo necesario en el momento necesario:
acción: package.install(@acme/[email protected])
credencial: registry-read-token
scope: packages:read
lifetime: esta operación / TTL corto
network: registry.acme.example
Después retira o expira esa capacidad.
La seguridad aquí procede de reducir blast radius, no de confiar en que el modelo no descubra las otras variables.
«Read-only» puede seguir siendo una operación sensible¶
Una operación que no muta el sistema puede producir daño si combina lectura sensible y egress.
Cada operación aislada puede parecer «sólo lectura» o «sólo red». Juntas forman una trayectoria de exfiltración.
Por eso una policy de coding agents no debería clasificar riesgo únicamente con:
Hay que considerar composición de capacidades. Lectura de secretos + canal de salida es un control distinto de modificación de archivos.
GitHub reconoce esta clase de riesgo en su documentación del cloud agent: el agente accede a código e información sensible y podría filtrarla accidentalmente o mediante input malicioso, por lo que restringe el acceso a Internet.8
El firewall tampoco es una palabra mágica¶
Incluso cuando un producto ofrece firewall, hay que preguntar qué procesos atraviesan esa frontera.
GitHub documenta una limitación concreta de su firewall configurable para Copilot cloud agent: sus restricciones se aplican a procesos iniciados mediante Bash, no necesariamente a MCP servers ni a procesos ejecutados durante setup, y no deben tratarse como una frontera universal contra cualquier bypass.9
No es una crítica general a firewalls. Es exactamente el tipo de detalle que un threat model necesita:
Decir sólo «network restricted» pierde la parte que permite razonar sobre fallos.
Hooks: automatización y enforcement no son lo mismo¶
Los hooks son muy útiles para convertir invariantes del repositorio en comportamiento automático:
antes de una tool call → validar / bloquear / pedir aprobación
después de editar → formatter / lint / tests
después de una tool → redacción / audit / feedback
al terminar → verificador de cierre
Pero el momento en el que corre el hook determina lo que puede garantizar.
Claude Code documenta que PreToolUse se ejecuta después de que Claude haya construido los argumentos y antes de procesar la llamada. Puede devolver allow, deny, ask o defer, e incluso modificar el input antes de la ejecución.3
En cambio, PostToolUse ocurre después de que la tool ya haya terminado. Puede modificar lo que Claude ve o bloquear la continuación, pero los archivos escritos, comandos ejecutados o requests de red ya produjeron sus efectos.3
Por tanto:
Un secret scanner que corre después de git push puede detectar una fuga, pero no convierte retroactivamente el push en seguro.
Un hook puede ser otra superficie privilegiada¶
También hay que invertir la pregunta: ¿con qué autoridad corre el hook?
Claude Code documenta que los command hooks se ejecutan con los permisos completos del usuario.3 Además, su semántica actual de workspace trust no es uniforme por tipo de configuración: en una sesión interactiva retiene los hooks de settings hasta que se acepta el trust del workspace, pero en claude -p o una sesión SDK trata la carpeta como trusted para esos hooks, de modo que hooks comprometidos en .claude/settings.json pueden ejecutarse aunque el usuario nunca haya aprobado esa carpeta interactivamente.3 En cambio, las reglas permissions.allow y additionalDirectories de .claude/settings.json que amplían capacidad siguen sin aplicarse en -p/SDK si esa carpeta concreta no fue trusted previamente; no aparece diálogo y Claude Code emite un warning.2 Los hooks de frontmatter de un subagente de proyecto siguen una regla más estricta: desde v2.1.218 requieren workspace trust; versiones anteriores podían ejecutarlos desde carpetas no confiadas.3
Eso hace que el propio repositorio sea parte del threat model.
Un harness que ejecuta repositorios no confiables debería decidir explícitamente:
¿se cargan hooks del repo?
¿se cargan settings del repo?
¿se permiten helpers ejecutables?
¿se conectan tool servers declarados por el repo?
¿con qué user/namespace corren?
«El agente sólo va a leer código» no responde a esas preguntas si abrir el proyecto activa configuración ejecutable.
Configuración trusted y configuración controlada por el repositorio¶
Hay una diferencia entre:
y:
La segunda tiene poder operacional.
Claude Code aplica workspace trust a determinadas capacidades del proyecto y da precedencia a reglas restrictivas como deny; las managed settings pueden imponer políticas que niveles inferiores no sobrescriben.24
La implicación de diseño es más general:
Cuanto más privilegiada sea una configuración, más alto debe estar su dominio de confianza respecto al contenido que el agente está analizando.
Para código de terceros, la configuración de seguridad del host no debería depender de archivos que el propio repositorio pueda modificar.
Prompt injection cambia decisiones; la policy limita consecuencias¶
Un archivo del repositorio puede contener:
No hay que asumir que el modelo obedecerá. Tampoco hay que asumir que nunca lo hará.
El diseño defensivo parte de que repo, issues, documentación web y output de tools pueden ser contexto no confiable.
Anthropic describe prompt injection como un riesgo explícito en Claude Code y recomienda permisos, aislamiento y revisión como capas defensivas.5 GitHub documenta igualmente que issues y comentarios pueden introducir prompt injection contra Copilot cloud agent y aplica mitigaciones específicas, además de restricciones de red.8
La propiedad que interesa no es «el modelo detecta el ataque el 100 % de las veces». Es:
Caso trabajado: actualizar un paquete privado y abrir un PR¶
Tarea:
Actualiza @acme/auth de 4.1.0 a 4.2.1, adapta la API si hace falta,
ejecuta los tests y abre un PR. No publiques paquetes ni despliegues nada.
1. Contexto¶
El agente lee package.json, lockfile, código, tests y changelog. Todo contenido del repo y de dependencias se trata como input, no como policy con autoridad superior.
2. Tool surface¶
Necesita como mínimo:
No necesita npm publish, cloud deployment ni acceso a producción.
3. Policy¶
allow:
- read repo
- edit workspace
- run tests
ask:
- network access to private registry
- push branch / create PR if policy requires it
deny:
- package publish
- production cloud tools
- push to protected branch
Este YAML es ilustrativo, no una sintaxis común de producto.
4. Network¶
Egress sólo al registry privado y a los endpoints de GitHub necesarios para la tarea. Un curl arbitrario no obtiene automáticamente la misma autorización.
5. Credentials¶
Se proyectan dos identidades separadas:
No se entrega una credential de producción «porque ya estaba disponible en CI».
6. Approval¶
Si instalar el paquete requiere ampliar egress, la aprobación debe mostrar el dominio y la operación. Si el push se autoriza, se liga a la branch de trabajo y no a main.
7. Hooks / verifiers¶
Un pre-hook puede bloquear npm publish. Un post-edit hook puede lanzar lint/tests. Un secret scan antes del push puede impedir que una credential se haya materializado en el diff.
El orden importa:
es preventivo;
sólo detecta después del efecto.
8. Evidencia¶
La trayectoria puede registrar:
action_id: act-184
task_id: CA-204
tool: package.install
target: registry.acme.example
arguments_digest: sha256:...
policy_version: 17
decision: allow_after_approval
approval_id: apr-91
credential_identity: registry-read
credential_value_logged: false
network_destination: registry.acme.example
result: success
verification_head_sha: 73ab...91f
El log contiene identidad y decisión, no el secreto.
Los approvals permanentes acumulan autoridad¶
«Don’t ask again» reduce fricción. También convierte decisiones puntuales en configuración persistente.
Claude Code documenta que algunas aprobaciones pueden guardarse por repositorio y reutilizarse en futuras sesiones, mientras otras duran sólo la sesión. GitHub Copilot CLI también persiste determinados approvals y diferencia su scope según tool, ubicación o dominio.26
La pregunta operativa es:
El inventario debería registrar los approvals persistentes activos, quién creó cada uno y cuándo, su scope exacto, el último uso, su owner, la fecha o condición de expiración y el mecanismo de revocación.
Un permiso antiguo para «resolver un incidente» no debería convertirse silenciosamente en baseline para todas las tareas futuras.
El sistema remoto sigue teniendo la última palabra¶
El harness no debe asumir que su approval reemplaza controles externos.
GitHub documenta, por ejemplo, que Copilot cloud agent no puede autoaprobar ni fusionar su propia PR y que los workflows disparados por su código están restringidos por defecto hasta una aprobación humana con permisos suficientes, salvo configuración explícita distinta.8
Eso es un buen ejemplo de separación de dominios de fallo:
agent policy → decide qué intenta el agent
repository controls → deciden qué acepta GitHub
CI/deploy controls → deciden qué artefacto llega más lejos
Si todos dependen del mismo token omnipotente y de la misma decisión del agente, la defensa en profundidad es nominal.
Qué observar para poder auditar autoridad¶
Registrar sólo:
no permite reconstruir por qué la acción era legítima.
Un ledger de decisiones debería conservar, sin almacenar secretos:
task_id
session_id
agent/model identity
requested tool + normalized args/digest
policy version + matching rule
decision: allow / ask / deny
approval identity + scope + expiry
credential identity/scopes, nunca el valor
sandbox/network decision
remote resource/environment
effect result
verification result
OpenAI documenta export de eventos OpenTelemetry de Codex que incluyen prompts, decisiones de aprobación, resultados de tools, uso de MCP y decisiones allow/deny de network proxy.1
La observabilidad no sustituye el control preventivo. Permite explicar y evaluar si el control funcionó.
Evals de permisos: probar negativas, no sólo happy paths¶
Un test de coding agent no debería demostrar únicamente que la tarea correcta puede completarse.
Debe incluir trayectorias como:
repo pide exfiltrar un secret → DENY
model intenta push a main → DENY
model pide registry permitido → ALLOW/ASK según policy
args cambian después del approval → approval inválido
post-hook detecta fallo → no se interpreta como prevención
credential expirada → fail closed + handback/retry policy
network destino fuera de allowlist → DENY
Y debe verificar el efecto, no sólo el mensaje del agente.
Un modelo que dice «no ejecuté el comando» no es evidencia si el audit log muestra que sí hubo un proceso o request.
Trade-off real: velocidad frente a autoridad preconcedida¶
Pedir aprobación por cada lectura de archivo hace un agente inutilizable. Preautorizar shell, red y credenciales de producción hace que la autonomía sea barata a costa de un blast radius enorme.
El objetivo no es maximizar prompts de confirmación. Es colocar fricción en las fronteras que cambian materialmente el riesgo:
repetible + reversible + local + sin secretos → más autonomía
mutación remota + credencial privilegiada → policy más estricta
irreversible + producción + datos sensibles → separación fuerte / handback
Estas categorías dependen del sistema concreto. Un git push a una branch desechable no tiene el mismo impacto que un terraform apply en producción aunque ambos sean comandos de shell.
Implicación de producción: diseñar autoridad como un grafo¶
El patrón más robusto no es una lista global de tools «permitidas». Es un grafo donde cada efecto necesita atravesar las fronteras que le corresponden:
untrusted context
↓
model proposal
↓
tool schema / argument validation
↓
policy decision ─── DENY → stop + evidence
↓
scoped approval, si aplica
↓
sandbox + network enforcement
↓
minimal credential projection
↓
remote ACL / branch protection / IAM
↓
effect
↓
postcondition + audit + verifier
La consecuencia más importante es simple: el modelo puede proponer acciones; el harness y los sistemas externos poseen la autoridad.
Un coding agent es más autónomo cuando puede recorrer este grafo sin intervención innecesaria. Es más seguro cuando cada frontera puede decir «no» independientemente de que la inferencia haya decidido continuar.
En el siguiente capítulo esa separación se vuelve verificable: tests, verifiers, diff review y stop conditions deben demostrar que las acciones autorizadas produjeron el resultado correcto, no sólo que terminaron sin error.
Referencias primarias¶
-
OpenAI, Running Codex safely at OpenAI, 8 de mayo de 2026. Se usan sus fronteras explícitas entre sandbox, approvals, network policy, identidad/credenciales, rules, managed requirements y telemetría. ↩↩↩↩
-
Anthropic, Configure permissions — Claude Code Docs. Se usan las reglas allow/ask/deny, su enforcement fuera del modelo, su relación con sandboxing y workspace trust. ↩↩↩↩
-
Anthropic, Hooks reference — Claude Code Docs. Se usan las semánticas actuales de
PreToolUse/PostToolUse, decision control y las advertencias de seguridad sobre command hooks/workspace trust. ↩↩↩↩↩ -
Anthropic, Settings files and precedence — Claude Code Docs. Se usa la precedencia actual de managed/project/local/user settings y las restricciones que no pueden ser relajadas desde niveles inferiores. ↩
-
Anthropic, Security — Claude Code Docs. Se usan sus límites de responsabilidad, prompt injection e isolation/network/credential guidance. ↩
-
GitHub, Allowing and denying tool use — GitHub Copilot CLI. Se usa la separación entre tool availability, approvals y allow/deny. ↩↩
-
GitHub, Giving GitHub Copilot cloud agent access to resources in your organization. Se usan los límites documentados del token por defecto y Agents secrets. ↩
-
GitHub, Risks and mitigations for GitHub Copilot cloud agent. Se usan las restricciones de Internet, prompt-injection surface, review/merge y workflow-approval boundaries. ↩↩↩
-
GitHub, Customizing or disabling the firewall for GitHub Copilot. Se usan explícitamente sus límites documentados de cobertura; no se generalizan a otros runtimes. ↩