40+ Herramientas y el Motor de Permisos Tri-State
El catálogo completo de tools organizado en 6 conjuntos de acceso, evaluación en cascada de 4 fuentes, y el yolo classifier — literalmente una IA juzgando si la acción de otra IA es segura.
¿Dejarías que una IA decida si otra IA puede borrar tu código? Claude Code tiene un modo llamado "yolo" donde exactamente eso sucede. Pero también tiene el sistema de permisos más granular de cualquier coding tool. La tensión entre autonomía y seguridad, resuelta con ingeniería.
La Interfaz de Cada Tool
Anatomía de una herramienta
Cada herramienta en Claude Code implementa una interfaz que declara no solo qué hace, sino qué tan peligrosa es. Cuatro propiedades de seguridad determinan cómo el sistema de permisos la trata:
| Propiedad | Propósito | Impacto |
|---|---|---|
isReadOnly() | ¿Modifica estado? | Afecta evaluación de permisos |
isDestructive() | ¿Puede causar daño irreversible? | Trigger de confirmación explícita |
isConcurrencySafe() | ¿Puede ejecutarse en paralelo? | Habilita parallel tool calls |
interruptBehavior() | ¿Qué pasa si el usuario interrumpe? | allow = parar · block = debe completar |
interface Tool {
name: string
call(input): Promise<ToolResult>
// Safety properties
isReadOnly(): boolean // sin side effects
isDestructive(): boolean // confirmación explícita requerida
isConcurrencySafe(): boolean // puede correr en paralelo
// Deferred loading
shouldDefer: boolean // carga bajo demanda vía ToolSearch
searchHint: string // keywords para matching
// Output control
maxResultSizeChars: number // default: 50,000 chars
} Catálogo de 40+ Herramientas
El registro completo por categoría
Core Tools (Siempre Disponibles)
| Tool | Descripción | ReadOnly | Concurrent |
|---|---|---|---|
BashTool | Ejecución de comandos shell | ❌ | ❌ |
FileReadTool | Leer contenido de archivos | ✅ | ✅ |
FileEditTool | Editar archivos existentes | ❌ | ❌ |
FileWriteTool | Crear/sobreescribir archivos | ❌ | ❌ |
GlobTool | Búsqueda por patrones de archivo | ✅ | ✅ |
GrepTool | Búsqueda de texto en archivos | ✅ | ✅ |
WebFetchTool | HTTP fetch | ✅ | ✅ |
WebSearchTool | Búsqueda web | ✅ | ✅ |
NotebookEditTool | Edición de Jupyter notebooks | ❌ | ❌ |
PowerShellTool | Windows PowerShell | ❌ | ❌ |
Agent & Task Tools
| Tool | Descripción | Gate |
|---|---|---|
AgentTool | Spawn de sub-agentes | Siempre |
TaskOutputTool | Retornar resultados al padre | Siempre |
AskUserQuestionTool | Preguntar al usuario | Siempre |
SkillTool | Ejecutar skills bundled/custom | Siempre |
ToolSearchTool | Buscar tools diferidos | Siempre |
EnterPlanModeTool | Entrar en modo plan | Siempre |
Gated Tools (Feature Flags)
| Tool | Gate | Descripción |
|---|---|---|
WebBrowserTool | WEB_BROWSER | Navegador web completo |
LSPTool | LSP_TOOL | Language Server Protocol |
WorktreeCreateTool | Worktrees | Crear git worktree |
SendMessageTool | UDS_INBOX | Enviar mensaje a peer agent |
TeamCreateTool | Swarms | Crear equipo de agentes |
SleepTool | KAIROS | Dormir al agente |
CronCreateTool | AGENT_TRIGGERS | Programar cron job |
PushNotificationTool | KAIROS | Push notification al usuario |
SubscribePRTool | KAIROS_GITHUB | Suscribir a webhooks de PR |
Deferred Tool Loading
Tools con shouldDefer = true NO se envían al API en cada request.
Cuando el modelo necesita una, llama a ToolSearchTool, que hace matching
por keywords y la carga bajo demanda. Esto reduce el payload inicial — fewer tool definitions = fewer tokens.
6 Conjuntos de Acceso
Quién puede usar qué
Agent-Disallowed
Lo que sub-agentes NO pueden hacer: TaskOutput, PlanMode, AskUser, TaskStop
Async Agent
Tools para agentes background: FileRead, Bash, Grep, Edit + Worktrees si están habilitados
Coordinator-Only
Solo 4 tools: Agent, TaskStop, SendMessage, SyntheticOutput
In-Process Teammate
Solo gestión: TaskCreate/Get/Update/List, SendMessage, Cron
Simple Mode
Mínimo viable: Bash + FileRead + FileEdit. Nada más.
REPL Mode (Ant-Only)
Todo dentro de un VM REPL. Oculta todas las tools primitivas.
El Principio de Diseño
Cada tipo de agente recibe exactamente las herramientas que necesita y nada más. El coordinador no puede ejecutar código directamente — solo delegar. Los sub-agentes no pueden hablar con el usuario — solo reportar al padre. Es mínimo privilegio aplicado a AI agents.
Motor de Permisos
Evaluación en cascada con 4 fuentes
Cada request de tool pasa por un pipeline de evaluación: deny first, luego allow, luego mode-based default. Las reglas vienen de 4 fuentes en cascada — cada una puede override la anterior.
Flujo de Evaluación
Tool request arrives
│
├── Check DENY rules first (cascading sources)
│ └── Match → REJECT immediately
│
├── Check ALLOW rules (with glob/path matching)
│ └── Match → APPROVE
│
├── Fall back to mode-based default
│ ├── bypassPermissions → APPROVE
│ ├── plan → PROPOSE (mostrar plan, pedir aprobación)
│ ├── auto → yoloClassifier (IA decide si es seguro)
│ └── default → check risk level
│ ├── LOW → APPROVE
│ ├── MEDIUM → APPROVE (within project scope)
│ └── HIGH → ASK user
│
└── Si ASK → Prompt de confirmación al usuario 4 Fuentes de Reglas (Cascading)
Platform
Defaults de Anthropic — la base
Organization
Políticas de Enterprise/equipo — fetched del API
Project
.claude/settings.json en la raíz del proyecto
User
~/.claude/settings.json en el home del usuario
El Yolo Classifier
IA juzgando si la acción de otra IA es segura
Cuando el modo de permisos es auto, Claude Code hace
una llamada LLM para clasificar si la operación es segura:
- •
bashClassifier.ts— para comandos shell - •
yoloClassifier.ts— para operaciones generales
Es literalmente una IA juzgando si otra IA es segura — AI safety recursiva.
Denial Tracking — Circuit Breaker
Patrón circuit breaker: después de N rechazos consecutivos, el sistema cambia su estrategia — deja de intentar operaciones similares. Evita loops infinitos de "intento → rechazo → intento → rechazo".
Taxonomía de Riesgo
LOW · MEDIUM · HIGH
LOW — Auto-aprobado
read, search, format, git status, glob, grep
Sin side effects, sin riesgo. Se aprueba siempre.
MEDIUM — Aprobado en contexto
write, create branch, build, install dependencies
Side effects contenidos dentro del proyecto. Se aprueba si está dentro del scope.
HIGH — Confirmación explícita
rm -rf, DROP TABLE, git push --force, publish packages
Potencialmente irreversible. Siempre requiere confirmación del usuario.
Plan Mode
Proponer antes de ejecutar
EnterPlanModeTool / ExitPlanModeV2Tool —
el modelo propone operaciones en vez de ejecutarlas.
El usuario revisa el plan y aprueba o rechaza.
Ideal para: cambios grandes, equipos con procesos de review, auditorías de seguridad, o cuando simplemente quieres entender qué va a hacer antes de que lo haga.
Límites y Truncación
Los guardrails numéricos
| Límite | Valor | Contexto |
|---|---|---|
MAX_RESULT_SIZE_CHARS | 50,000 | Por resultado de tool |
MAX_TOOL_RESULT_TOKENS | 100,000 | Por resultado (tokens) |
MAX_TOOL_RESULT_BYTES | 400,000 | Por resultado (bytes) |
MAX_RESULTS_PER_MESSAGE | 200,000 | Total por turno (chars) |
IMAGE_MAX_SIZE | 5 MB | Por imagen (base64) |
PDF_MAX_SIZE | 20 MB | Máx por PDF |
PDF_MAX_PAGES | 100 | Máx páginas por PDF |
MAX_MEDIA_PER_REQUEST | 100 | Imágenes/PDFs por request |
Patrones Reutilizables
Lo que puedes copiar para tus AI agents
Permission cascading (platform → org → project → user) — 4 niveles de reglas donde cada uno puede override el anterior. Más flexible que un sistema binario allow/deny de un solo nivel.
Tri-state (allow/deny/ask) en vez de binary — el tercer estado "ask" permite decisiones contextuales sin bloquear el flujo de trabajo completo.
AI-as-judge para auto-approval — arriesgado pero efectivo. El yolo classifier es un pragmatismo que reconoce que enumerar todas las reglas posibles es imposible; una IA generalista puede cubrir los edge cases.
Risk taxonomy con 3 categorías claras — LOW/MEDIUM/HIGH con comportamientos diferentes para cada nivel. Simple, comprensible, extensible.