Armá un Agente de Auditoría de Repos con el Claude Agent SDK (y Conocé sus Límites)

1. El Problema: un Agente con Shell y Sin Política

Un agente de auditoría de repos tiene que leer mucho y ejecutar unos pocos comandos. La demo más rápida le da Bash y apaga las aprobaciones, y funciona, hasta que audita un repositorio que no escribiste vos. Un README, un comentario o un nombre de archivo pueden llevar instrucciones, y un modelo que siga una la va a ejecutar con tus privilegios. La guía de despliegue de Anthropic plantea el modelo de amenazas sin vueltas: los agentes pueden tomar acciones no previstas por prompt injection o por simple error del modelo. La mirada de diseño está en mi deep dive sobre prompt injection; este post es el lado de la implementación.

Lo que construimos en cambio es una política en capas, en un solo archivo de menos de 200 líneas: disponibilidad (qué ve Claude), aprobación (qué corre sin preguntar), un hook (qué se rechaza pase lo que pase) y un callback (qué pasa con todo lo demás). Versiones que fijé: claude-agent-sdk 0.2.167 en PyPI (Python 3.10 o superior, subido el 14 de octubre de 2026) y @anthropic-ai/claude-agent-sdk 0.3.300 en npm. El ritmo de releases es rápido y los docs condicionan varias funciones por versión, así que fijá la versión y leé el changelog antes de actualizar.

2. Conceptos Mínimos Antes de Tocar Código

Seis ideas explican cada línea de abajo. Python y TypeScript las comparten; elegí Python porque los docs traen ejemplos completos de hooks, callbacks y subagentes ahí (algunos eventos de hook existen solo en TypeScript, lo aclaro más adelante).

3. Paso 1: Instalar y Escribir la Tool Propia

Los dos SDKs incluyen un binario nativo de Claude Code en la mayoría de las instalaciones, así que en general alcanza con un pip install. La autenticación es una ANTHROPIC_API_KEY en el entorno del proceso que corre el agente; el SDK no carga archivos .env por vos. Salvo aprobación previa, Anthropic no permite que productos de terceros ofrezcan login de claude.ai en agentes hechos con el SDK, así que usá autenticación por API key.

Shell: instalar y autenticar

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\Activate.ps1
pip install "claude-agent-sdk==0.2.167"

export ANTHROPIC_API_KEY=your-api-key      # PowerShell: $env:ANTHROPIC_API_KEY = "your-api-key"

La tool cuenta marcadores TODO, FIXME y HACK por archivo. Es aburrida a propósito, porque lo interesante es lo que valida: la ruta tiene que resolver dentro del repo, se saltean los symlinks, y los fallos devuelven is_error para que Claude pueda reaccionar en vez de que se atragante el loop. La anotación readOnlyHint le permite agruparla con otras llamadas de solo lectura.

Python: audit_agent.py, parte 1 (imports y la tool propia)

# audit_agent.py, part 1: imports and the custom tool
import asyncio
import re
import shlex
import sys
from pathlib import Path
from typing import Annotated, Any

from claude_agent_sdk import (
    AgentDefinition, AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient,
    HookMatcher, ResultMessage, TextBlock, ToolAnnotations,
    create_sdk_mcp_server, tool,
)
from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny

REPO = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
MARKERS = ("TODO", "FIXME", "HACK")
SKIP = {".git", "node_modules", ".venv", "__pycache__"}


@tool(
    "todo_report",
    "Count TODO/FIXME/HACK markers per file under a repo-relative directory",
    {"directory": Annotated[str, "Repo-relative directory to scan, for example src"]},
    annotations=ToolAnnotations(readOnlyHint=True),
)
async def todo_report(args: dict[str, Any]) -> dict[str, Any]:
    target = (REPO / args["directory"]).resolve()
    if not target.is_relative_to(REPO) or not target.is_dir():
        msg = f"Not a directory inside the repo: {args['directory']}"
        return {"content": [{"type": "text", "text": msg}], "is_error": True}

    rows = []
    for path in target.rglob("*"):
        rel = path.relative_to(REPO)
        if path.is_symlink() or not path.is_file() or SKIP & set(rel.parts):
            continue
        try:
            text = path.read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError):
            continue
        hits = sum(text.count(marker) for marker in MARKERS)
        if hits:
            rows.append((hits, rel.as_posix()))

    rows.sort(reverse=True)
    lines = [f"{n:3d}  {p}" for n, p in rows[:20]] or ["No markers found."]
    return {"content": [{"type": "text", "text": "\n".join(lines)}]}


audit_server = create_sdk_mcp_server(name="audit", version="1.0.0", tools=[todo_report])

4. Paso 2: Un Hook PreToolUse que Bloquea Bash Riesgoso

Los hooks son callbacks que el SDK ejecuta en puntos del ciclo de vida. PreToolUse se dispara antes de que corra una herramienta y recibe tool_name y tool_input; para Bash, tool_input.command es el texto completo del comando. Un hookSpecificOutput con permissionDecision “deny” bloquea la llamada, y permissionDecisionReason le explica al modelo por qué para que no reintente lo mismo. Devolver {} deja la decisión al resto del flujo de permisos.

Python: parte 2 (guardas y registro)

# part 2: PreToolUse guards (they run before every other permission step)
RISKY_BASH = [
    (re.compile(r"\brm\b.*\s(-\w*[rR]\w*|--recursive)\b"), "recursive delete"),
    (re.compile(r"\b(curl|wget)\b.*\|\s*(ba|z)?sh\b"), "download piped into a shell"),
    (re.compile(r"\b(sudo|chmod|chown|mkfs|dd)\b"), "privilege or disk change"),
    (re.compile(r"\.env\b|\.ssh\b|\.aws\b|id_rsa|\.npmrc"), "credential path"),
]
SECRET_PATH = re.compile(r"(^|[\\/])(\.env(\..+)?|id_rsa|\.npmrc)$|[\\/]\.(ssh|aws)[\\/]")
GIT_AT_START = re.compile(r"(^|[;&|]\s*)git\b")
SHELL_META = re.compile(r"[;&|<>$\n\x60]")  # \x60 is a backtick
SAFE_GIT = {"log", "diff", "show", "status", "ls-files", "shortlog"}


def deny(reason: str) -> dict[str, Any]:
    return {
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": f"Blocked by audit policy: {reason}",
        }
    }


def harden_git(command: str) -> str | None:
    """Rewrite a simple read-only git command so repo-controlled config cannot run code."""
    if SHELL_META.search(command):
        return None
    try:
        parts = shlex.split(command)
    except ValueError:
        return None
    if len(parts) < 2 or parts[0] != "git" or parts[1] not in SAFE_GIT:
        return None
    if any(p.startswith("--output") for p in parts):
        return None  # git diff --output=<file> writes a file
    extra = ["--no-ext-diff", "--no-textconv"] if parts[1] in {"diff", "show", "log"} else []
    return shlex.join(["git", "-c", "core.fsmonitor=false", parts[1], *extra, *parts[2:]])


async def guard_bash(input_data, tool_use_id, context):
    command = input_data["tool_input"].get("command", "")
    for pattern, label in RISKY_BASH:
        if pattern.search(command):
            return deny(f"{label}. This agent is read-only.")
    hardened = harden_git(command)
    if hardened:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "allow",
                "permissionDecisionReason": "read-only git, config hardened",
                "updatedInput": {**input_data["tool_input"], "command": hardened},
            }
        }
    if GIT_AT_START.search(command):
        return deny("only simple read-only git commands are available (log, diff, show, status, ls-files, shortlog).")
    return {}  # no opinion: the rest of the permission flow decides


async def guard_reads(input_data, tool_use_id, context):
    if SECRET_PATH.search(input_data["tool_input"].get("file_path", "")):
        return deny("secret files are out of scope for this audit.")
    return {}


HOOKS = {
    "PreToolUse": [
        HookMatcher(matcher="Bash", hooks=[guard_bash]),
        HookMatcher(matcher="Read", hooks=[guard_reads]),
    ]
}

Fijate que el hook hace dos trabajos. Rechaza lo que reconoce y reescribe lo que permite. Los comandos de solo lectura integrados, como cat, ls y las formas read-only de git, corren sin prompt en todos los modos, así que un callback nunca los ve; el hook sí. Git es el caso filoso: lee config que controla el repositorio, la clase de bug detrás de GitSpawn. Por eso los comandos git simples de solo lectura se reescriben con core.fsmonitor=false (más --no-ext-diff y --no-textconv en los subcomandos tipo diff, la llamada endurecida que recomienda ese post) y cualquier otra invocación de git se rechaza. Cuando un hook deniega, escribí un motivo que diga qué hacer en su lugar; varios hooks del mismo evento corren en paralelo y aplica el resultado más restrictivo.

5. Paso 3: La Política de Permisos, Disponibilidad, Aprobación y Callback

Ahora las capas que deciden qué pasa cuando el hook no opina. La lista tools controla la disponibilidad: los built-ins que dejás afuera no están en el contexto de Claude, así que no hay Edit ni Write que aprobar o denegar. allowed_tools preaprueba las herramientas de lectura, la tool Agent y nuestra tool propia por su nombre completo, mcp__audit__todo_report. Bash está ausente de allowed_tools a propósito, porque las tools de esa lista se saltean can_use_tool.

Python: parte 3 (el callback de permisos)

# part 3: the permission callback, the last resort
async def audit_policy(tool_name, input_data, context):
    """Runs only when nothing earlier decided and the call would have asked a human."""
    summary = f"{tool_name}: {str(input_data)[:120]}"
    if sys.stdin.isatty():
        answer = await asyncio.to_thread(input, f"Allow {summary} ? [y/N] ")
        if answer.strip().lower() == "y":
            return PermissionResultAllow(updated_input=input_data)

    print(f"[policy] denied {summary}", file=sys.stderr)
    return PermissionResultDeny(
        message=(
            f"{tool_name} was not approved. This is a read-only audit: "
            "use Read, Grep, Glob, todo_report or read-only git commands."
        )
    )

Dos detalles más. Pasá permission_mode=“default” explícitamente: si lo omitís, el modo inicial puede ser auto mode, que descarta reglas allow amplias. Y si querés deny por defecto sin ningún callback, permission_mode=“dontAsk” convierte cada prompt en un rechazo y nunca llama a can_use_tool.

6. Paso 4: un Subagente Enfocado, las Opciones y el Loop de Ejecución

Un subagente es una instancia de agente separada que el agente principal arranca vía la tool Agent. El historial del padre y los resultados de sus tools no se le pasan, y solo vuelve el mensaje final del subagente, así que un revisor puede leer decenas de archivos sin inflar la conversación principal. Restringilo con tools y dale un modelo barato: model acepta un alias como haiku, sonnet, opus o inherit, o un ID de modelo completo. La cuenta de costos de los workers chicos está en la guía de subagentes con Haiku 5.5.

Python: parte 4 (subagente, opciones y loop de ejecución)

# part 4: subagent, options and the run loop
REVIEWER = AgentDefinition(
    description="Reviews ONE directory for test gaps and risky config. Use it once per directory.",
    prompt=(
        "You are a focused code reviewer. Inspect only the directory you are given. "
        "Report at most five findings, each with a file path, a line reference and a one-line fix. "
        "You are read-only: never propose running commands."
    ),
    tools=["Read", "Grep", "Glob"],
    model="haiku",
    maxTurns=15,  # camelCase on purpose: AgentDefinition uses wire-format field names
)

OPTIONS = ClaudeAgentOptions(
    system_prompt=(
        "You are a read-only repo-audit agent. Start with todo_report on the main source "
        "directory, delegate one directory at a time to the test-gap-reviewer subagent, "
        "then answer with a ranked list: file, risk, one-line fix."
    ),
    cwd=str(REPO),
    setting_sources=[],  # do not load the audited repo's .claude settings or hooks
    tools=["Read", "Grep", "Glob", "Bash", "Agent"],  # availability: no Edit, Write or web
    allowed_tools=["Read", "Grep", "Glob", "Agent", "mcp__audit__todo_report"],  # approval
    mcp_servers={"audit": audit_server},
    permission_mode="default",  # say it out loud: the built-in default can be auto mode
    can_use_tool=audit_policy,
    hooks=HOOKS,
    agents={"test-gap-reviewer": REVIEWER},
    max_turns=30,
    max_budget_usd=2.0,
)


def show(message) -> None:
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(block.text)
    elif isinstance(message, ResultMessage):
        print(f"[{message.subtype}] turns={message.num_turns} cost={message.total_cost_usd}")


async def main() -> None:
    async with ClaudeSDKClient(options=OPTIONS) as client:
        await client.query("Audit this repository and give me the ranked findings.")
        async for message in client.receive_response():
            show(message)

        # same client = same session: the follow-up keeps all the context
        await client.query("Keep only the top three, each with the exact file and the fix.")
        async for message in client.receive_response():
            show(message)


asyncio.run(main())

Tres detalles merecen una segunda mirada. Los campos de AgentDefinition mantienen camelCase (maxTurns, disallowedTools), y un keyword en snake_case lanza TypeError al construirlo. setting_sources=[] evita que se carguen los settings .claude y los hooks de shell del repo auditado, cosa que las opciones por defecto sí harían. Y tus hooks PreToolUse también se disparan dentro del subagente, con agent_id y agent_type seteados, así que registralos. Para acotar anidamiento y paralelismo, los docs dan las variables CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH y CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (se pasan por env) y max_budget_usd.

7. Qué Garantiza y Qué No Garantiza Esta Política

Todo lo anterior es política: código que corre dentro del propio límite de confianza del agente e inspecciona texto. Los docs son directos al respecto. El parseo de comandos para permisos es “una compuerta de permisos, no un sandbox”, y una regla deny de Bash “no es un límite de seguridad alrededor del programa”. Tomá las tres cajas de abajo como el balance honesto.

Python: settings opcionales del sandbox del SDK para Bash

# optional wall for Bash: pass it as ClaudeAgentOptions(sandbox=SANDBOX)
SANDBOX = {
    "enabled": True,
    "failIfUnavailable": True,          # Python default: run unsandboxed with a warning
    "allowUnsandboxedCommands": False,  # the model may not ask to leave the sandbox
    "network": {"allowedDomains": []},  # no outbound hosts for sandboxed commands
}

Ojo con la plataforma: el sandbox depende del soporte del SO (bubblewrap y socat en Linux, según los docs), y su proxy de red filtra por hostname sin inspeccionar TLS, así que técnicas como el domain fronting potencialmente pueden esquivarlo. Reduce el radio de daño; no vuelve confiable al agente.

8. Errores Comunes (la Mayoría Son Trampas Documentadas)

Casi cualquier falla que esperaría de este setup es una de estas. La columna izquierda es lo que aguanta; la derecha, lo que muerde.

Conclusión

Ya tenés el loop completo: una tool propia como servidor MCP en proceso, un hook PreToolUse que rechaza y reescribe, un callback como red de deny por defecto y un subagente de solo lectura con un modelo barato, todo dentro de una sola sesión. La forma se traslada a TypeScript casi línea por línea (tool() con Zod, createSdkMcpServer, hooks y canUseTool), y el SDK de TypeScript tiene eventos de hook extra como SessionStart y PostToolBatch que los callbacks de Python no tienen.

Lo que sigue, por orden de valor: convertí los cuatro prompts del smoke test en aserciones que corran en CI, mové el proceso a un contenedor con el repo montado en solo lectura, y empaquetá las instrucciones de auditoría como un skill reutilizable, que explica el tutorial de Agent Skills. Releé el changelog antes de cada actualización del SDK: los propios docs anotan comportamientos que cambiaron entre releases.

Fuentes

• Quickstart del Agent SDK (instalación, ANTHROPIC_API_KEY, primer agente)
• Referencia Python del Agent SDK (ClaudeAgentOptions, hooks, AgentDefinition, sandbox)
• Hooks del Agent SDK (PreToolUse, matchers, salidas, timeouts)
• Permisos del Agent SDK (orden de evaluación, allowed_tools, modos)
• Aprobaciones e input del usuario en el Agent SDK (callback can_use_tool)
• Tools propias del Agent SDK (@tool, servidor MCP en proceso)
• Subagentes del Agent SDK (AgentDefinition, herencia, límites)
• Despliegue seguro de agentes de IA (modelo de amenazas, aislamiento, credenciales)
• Permisos de Claude Code (límites de las reglas Bash)
• PyPI: claude-agent-sdk (0.2.167, Python 3.10+)
• npm: @anthropic-ai/claude-agent-sdk (0.3.300)
• Manual de Git: git diff (opción --output)