Agent Harness seguro para Claude Code y Codex: permisos, verificacion y rollback

Los agentes potentes necesitan una base segura

Cuando empiezas con Claude Code o Codex, parece que todo depende del prompt. Para pequenos cambios, funciona. Pero cuando el agente empieza a tocar despliegues, APIs de SaaS, archivos locales, publicaciones o emails, el problema deja de ser el prompt y pasa a ser la estructura de ejecucion.

En este articulo llamo Agent Harness a esa estructura externa: reglas de permisos, plan de trabajo, verificaciones, logs y mecanismo de recuperacion. El agente puede razonar y proponer cambios, pero no debe ejecutar cualquier comando sin control.

Para entender primero el concepto, lee la guia de harness engineering. Para ver fallos concretos, consulta casos de fallo de seguridad con Claude Code.

User request
  |
  v
Agent
  |
  v
[1] Policy layer       Que se permite, que pregunta, que se bloquea
[2] Plan layer         Que pasos se ejecutan y en que orden
[3] Verification layer Como se demuestra que funciono
[4] Recovery layer     Como se revierte un fallo
  |
  v
Files / shell / SaaS APIs / deploy

La documentacion oficial de Claude Code separa settings, permissions, hooks y MCP. Puedes empezar por Claude Code settings, Hooks reference y MCP.

Ejemplo: publicar un articulo

“Publica un articulo” no es una sola accion.

1. Leer analiticas de los ultimos 7 dias
2. Elegir un tema cercano a una pagina que ya crece
3. Revisar articulos existentes para evitar duplicados
4. Escribir el articulo base
5. Crear todas las versiones de idioma
6. Validar frontmatter, slug y enlaces internos
7. Ejecutar build
8. Comprobar la URL publicada
9. Hacer commit y push

Si esto vive solo en la memoria, el agente puede escribir el texto y olvidar la parte aburrida: traducciones, build, verificacion y despliegue. El Plan layer convierte esos pasos en una lista obligatoria.

SaaS: separar leer, generar y enviar

Supongamos que un agente busca empresas, genera una pagina de muestra y prepara emails comerciales.

Operacion	Automatico	Motivo
Leer paginas publicas	Si	Bajo impacto
Guardar CSV local	Si	Revisable
Generar pagina de muestra	Si	Se puede revisar antes
Redactar email	Si	Aun no se envia
Enviar email	Requiere aprobacion	Afecta a una persona real

El diseno del harness consiste en poner limites claros. Leer y redactar puede ser automatico. Publicar, enviar o modificar produccion debe pedir aprobacion.

Policy layer: allow, ask, deny

Un archivo de politica simple ya reduce mucho el riesgo.

{
  "allowCommands": [
    "npm run build",
    "npm run test",
    "node scripts/content-trend-report.mjs"
  ],
  "askCommands": [
    "git push",
    "wrangler pages deploy",
    "node scripts/outreach-send-mails.mjs --send"
  ],
  "denyCommands": [
    "rm -rf",
    "git reset --hard",
    "curl * | sh",
    "npm publish"
  ],
  "protectedPaths": [
    ".env",
    ".env.local",
    "claudecode-lab-sheets-f54fc47c68f0.json"
  ]
}

En Claude Code, una configuracion de proyecto puede expresar una frontera similar.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run test *)",
      "Bash(node scripts/content-trend-report.mjs *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(wrangler pages deploy *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git reset --hard *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./claudecode-lab-sheets-f54fc47c68f0.json)"
    ]
  }
}

La regla debe ser concreta. No basta con decir “ten cuidado con secretos”. Bloquea archivos, comandos destructivos y acciones externas.

Verification layer: comprobar con comandos

“Revisalo bien” no es una verificacion. Convierte el exito en comandos.

const url = process.argv[2];
const response = await fetch(url, { redirect: "follow" });

if (!response.ok) {
  throw new Error(`Page returned ${response.status}: ${url}`);
}

const html = await response.text();
const checks = [
  ["title", /<title>.+<\/title>/i],
  ["description", /<meta name="description"/i],
  ["adsense", /ca-pub-2125588229998303/i],
  ["analytics", /G-3YR0LE68MJ/i]
];

for (const [name, pattern] of checks) {
  if (!pattern.test(html)) throw new Error(`Missing ${name}`);
}

Para articulos con codigo, anade una prueba movil con Playwright para comprobar que pre, code y table no rompen el layout.

Recovery layer: saber que cambio

El fallo peligroso no es que el proceso falle. Lo peligroso es no saber que archivos modifico.

{
  "runId": "2026-05-19-article-001",
  "topic": "agent harness security",
  "changedFiles": [
    "site/src/content/blog/claude-code-codex-agent-harness-security.mdx"
  ],
  "commands": [
    "node scripts/content-trend-report.mjs --days 7",
    "npm run build"
  ],
  "status": "deployed"
}

Para Git, prefiere recuperacion dirigida.

git status --short
git diff -- site/src/content/blog/target-article.mdx
git revert <bad-commit>

Evita dar al agente acceso habitual a git reset --hard, especialmente en repositorios con cambios locales.

Checklist de implantación: empieza por el punto de salida

El primer mistake no suele ser técnico. Es dejar que el agente salte de “leer información” a “hacer una acción externa” sin una frontera clara. Por eso conviene definir el punto de salida de cada workflow antes de escribir prompts.

En contenido, el punto de salida no es “el artículo está escrito”. Es “la URL pública responde 200, los tags de Analytics y AdSense siguen presentes, y los bloques de código se ven bien en móvil”. En ventas, el punto de salida no es “el correo ya salió”. Es “hay una lista revisable de empresas, una página de muestra y un borrador de correo”. En una corrección de seguridad, el punto de salida no es “el agente cambió el código”. Es “hay diff, pruebas y rollback”.

use case	Automatizar primero	Mantener aprobación
Contenido	tema, borrador, traducción, enlaces internos, build	deploy, git push, cambios en anuncios
Integración SaaS	lectura, CSV, resumen, borrador de mensaje	envío, borrado, cambios de facturación
Seguridad	propuesta de patch, tests, notas de impacto	secretos, producción, permisos más amplios

El pitfall más peligroso es mezclar lectura con ejecución. Leer issues, documentación o páginas web es útil. Pero si el mismo agente también puede enviar emails, borrar datos o desplegar producción, una instrucción maliciosa dentro de una página externa puede convertirse en acción real. OWASP cubre riesgos como Prompt Injection y Excessive Agency en su Top 10 for LLM Applications, y ese marco encaja muy bien con agentes de código.

Para Claude Code, revisa la guía oficial de security y permissions. Para Codex, la guía de OpenAI sobre code generation ayuda a ubicar el producto dentro de flujos de ingeniería. Dentro de ClaudeCodeLab, combina este artículo con casos de fallo de seguridad y prompts peligrosos.

Si buscas plantillas listas para adaptar, están en /products/. Si necesitas diseñar permisos, CI, revisión y despliegue para un equipo, la ruta más rápida es /training/, porque el valor del harness aparece cuando el agente ya toca procesos reales del negocio.

Resumen

La calidad de un agente no depende solo del prompt. En trabajo real, depende del harness.

• Policy: que se permite, que pregunta y que se bloquea
• Plan: que va a ocurrir antes de ejecutarlo
• Verification: como se prueba que funciono
• Recovery: como se recupera un fallo

Claude Code y Codex tienen interfaces distintas, pero necesitan la misma idea: no convertir al agente en un ejecutor ilimitado, sino darle un camino seguro para trabajar.