Claude Code CLI — Análisis para CadencesLab

CadencesLab × Anthropic Partner Analysis
Documento de referencia arquitectónica del source code de Claude Code CLI
Para adaptación en: Cadences Platform, Synapse Studio, NutriNen Baby
Fecha: Abril 2026 | Actualizado: Julio 2026

⚡ Deep Analysis (Julio 2026)

Se ha realizado un análisis profundo completo del source code. Toda la documentación detallada está en la carpeta doc/:

Hallazgos clave del deep analysis:

1. Speculative Execution: Claude predice el siguiente prompt y lo ejecuta en un filesystem overlay
2. Dual Build: Empleados Anthropic tienen "never refuse" + word limits + REPL mode + Slack
3. KAIROS Mode: Asistente always-on con sleep/wake, push notifications, cron, PR webhooks
4. Dynamic Boundary: Separa prompt estático (cacheable) del dinámico (per-session)
5. Auto-Dream: Consolidación nocturna de memorias en 4 fases (Orient→Gather→Consolidate→Prune)

Índice

1. Resumen Ejecutivo
2. Arquitectura General de Claude Code
3. Sistemas Analizados
   • 3.1 Permission System
   • 3.2 Plugin/Marketplace System
   • 3.3 Hook System (Lifecycle Events)
   • 3.4 MCP (Model Context Protocol)
   • 3.5 Session/State Management
   • 3.6 Config Cascading
   • 3.7 Telemetry/Analytics
   • 3.8 Task/Todo System
   • 3.9 Skills System
   • 3.10 Agent Swarm
4. Comparación: Synapse Studio vs Claude Code Swarm
5. Patrones Cross-Cutting Reutilizables
6. Roadmap de Implementación para CadencesLab
7. Deep Dives Técnicos

Resumen Ejecutivo

El source code de Claude Code CLI (Anthropic) contiene ~800+ archivos TypeScript/TSX organizados en una arquitectura modular. El CLI usa Bun como runtime, React + Ink para UI de terminal, Commander.js para parsing de comandos, y @anthropic-ai/sdk para comunicación con la API.

Stack técnico de Claude Code

• Runtime: Bun (bundler + runtime)
• UI: React 18 + Ink (terminal rendering)
• CLI Framework: Commander.js
• AI SDK: @anthropic-ai/sdk
• Validation: Zod schemas
• File operations: Node.js fs + proper-lockfile
• Process isolation: AsyncLocalStorage, tmux, iTerm2

Lo que CadencesLab puede aprovechar

Arquitectura General

experimental/AnthropicsClaudeCode/src/
├── cli/              # CLI handlers, argument parsing
├── commands/         # Slash commands (/commit, /review, /plan, etc.)
├── components/       # React/Ink UI components
├── hooks/            # React hooks for terminal UI
├── services/         # MCP, analytics, session memory
│   ├── mcp/          # Model Context Protocol client
│   ├── analytics/    # Analytics tracking
│   └── mcpHub/       # MCP server hub
├── skills/           # Bundled skills (prompt templates)
├── tools/            # Tool implementations
│   ├── BashTool/     # Shell command execution
│   ├── FileEditTool/ # File editing with diffs
│   ├── FileReadTool/ # File reading
│   ├── GrepTool/     # Text search
│   ├── GlobTool/     # File pattern search
│   ├── AgentTool/    # Sub-agent spawning
│   ├── TaskCreateTool/ TaskUpdateTool/ TaskGetTool/ TaskListTool/
│   ├── TeamCreateTool/ TeamDeleteTool/
│   ├── WebFetchTool/ WebSearchTool/
│   └── ...
├── types/            # TypeScript type definitions
├── utils/            # Core utilities (~400 files)
│   ├── permissions/  # Permission engine
│   ├── plugins/      # Plugin marketplace system
│   ├── hooks/        # Lifecycle hooks (not React)
│   ├── settings/     # Cascading config
│   ├── telemetry/    # OpenTelemetry
│   ├── swarm/        # Multi-agent coordination
│   ├── model/        # Model selection/config
│   ├── bash/         # Shell parsing/safety
│   ├── mcp/          # MCP utilities
│   └── ...
└── vim/              # Vim mode for terminal input

Sistemas Analizados

3.1 Permission System

Ubicación: src/utils/permissions/

Arquitectura: Motor de permisos basado en reglas con tri-estado allow | deny | ask. Las reglas se evalúan en cascada desde múltiples fuentes.

Archivos clave:

• permissions.ts — Motor principal: hasPermissionsToUseTool()
• PermissionMode.ts — Enum: default, plan, acceptEdits, bypassPermissions, dontAsk, auto
• PermissionRule.ts — { source, ruleBehavior, ruleValue: { toolName, ruleContent? } }
• permissionsLoader.ts — Carga reglas de todas las fuentes de settings
• permissionRuleParser.ts — Serialización: "ToolName(content)" ↔ objeto
• yoloClassifier.ts — Clasificador AI para auto-approval en modo auto
• bashClassifier.ts — Clasificador de seguridad para comandos bash
• denialTracking.ts — Circuit breaker: tras N denials, cambia estrategia
• pathValidation.ts — Validación de paths con glob matching
• dangerousPatterns.ts — Patrones de comandos peligrosos

Flujo de evaluación:

Tool request → Load rules from all sources
             → Check deny rules first (reject if match)
             → Check allow rules (approve if match, with glob/path matching)
             → Fall back to mode-based default
             → If mode=auto → yoloClassifier LLM call
             → If ask → prompt user

Adaptación para Cadences:

CREATE TABLE permission_rules (
    id TEXT PRIMARY KEY,
    tenant_id TEXT NOT NULL,
    role TEXT NOT NULL,
    resource TEXT NOT NULL,
    action TEXT NOT NULL,
    behavior TEXT CHECK(behavior IN ('allow', 'deny', 'ask')),
    rule_content TEXT,  -- glob pattern or specific value
    source TEXT CHECK(source IN ('platform', 'org', 'project', 'user')),
    priority INTEGER DEFAULT 0
);

Evaluar en Workers con el mismo flujo: deny first → allow → default → ask (requiere aprobación humana vía webhook).

3.2 Plugin/Marketplace System

Ubicación: src/utils/plugins/

Arquitectura: Ecosistema completo con discovery, instalación, validación, caché, y versionado. Plugins = directorios con manifest JSON + código.

Archivos clave:

• pluginLoader.ts (~3300 líneas) — Ciclo completo: resolve → cache → clone/download → validate → load
• schemas.ts — Schemas Zod para plugin.json y marketplace.json
• validatePlugin.ts — Validación con Zod, path traversal checks, structural integrity
• marketplaceManager.ts — Gestión de marketplaces conocidos, caché de listings
• pluginVersioning.ts — Semver management
• pluginBlocklist.ts — Blocklist de plugins maliciosos
• pluginPolicy.ts — Enterprise policy enforcement
• reconciler.ts — Reconciliación de estado real vs deseado
• dependencyResolver.ts — Resolución de dependencias entre plugins

Manifest de plugin (schema):

{
    "name": "my-plugin",
    "version": "1.0.0",
    "description": "Plugin description",
    "commands": [{ "name": "/mycommand", "description": "..." }],
    "agents": [{ "name": "my-agent", "description": "..." }],
    "hooks": { "PreToolUse": [{ "type": "command", "command": "..." }] },
    "mcpServers": [{ "name": "my-server", "config": {} }]
}

Adaptación para Cadences: Sistema de "Integraciones" por tenant con manifest JSON + worker scripts + componentes UI, almacenados en R2. Tabla installed_integrations en D1.

3.3 Hook System

Ubicación: src/utils/hooks/, src/utils/hooks.ts

Arquitectura: Sistema event-driven donde hooks (shell commands, HTTP, prompts, funciones) se ejecutan en lifecycle events.

Eventos disponibles:

• PreToolUse / PostToolUse — Antes/después de cada tool call
• Stop — Cuando el agente termina su turno
• SessionStart / SessionEnd
• Notification — Para mensajes al usuario
• SubagentStart / SubagentStop
• TaskCreated / TaskCompleted
• ConfigChange / FileChanged / PermissionRequest

Tipos de hook:

type HookCommand = 
    | { type: 'command', command: string, timeout?: number }  // Shell
    | { type: 'http', url: string, method?: string }          // HTTP webhook
    | { type: 'prompt', prompt: string }                      // AI prompt
    | { type: 'agent', agent: string }                        // Sub-agent
    | { type: 'function', callback: Function }                // In-memory

AsyncHookRegistry: Hooks pueden retornar { "async": true, "asyncTimeout": 15000 } para ejecutarse en background. El registry trackea completions y los inyecta de vuelta.

Adaptación para Cadences:

// D1 schema
const hookEvents = [
    'onBookingCreated', 'onPaymentReceived', 'onReviewSubmitted',
    'onCustomerSignup', 'onOrderStatusChanged', 'onInventoryLow'
];

// Hook config por tenant en D1
// Ejecutar via Workers (sync) o Queues (async)
// El patrón AsyncHookRegistry → tracking de webhook delivery con retry

3.4 MCP (Model Context Protocol)

Ubicación: src/services/mcp/

Arquitectura: Cliente multi-transport que conecta con servidores MCP externos que proveen tools, resources, y prompts.

Transportes soportados:

• StdioClientTransport — Procesos locales via stdin/stdout
• SSEClientTransport — Server-Sent Events
• StreamableHTTPClientTransport — HTTP streaming
• WebSocketTransport — WebSocket bidireccional
• InProcessTransport — Mismo proceso (linked pair)
• SdkControlClientTransport — Bridge CLI ↔ SDK

Config scoping: Servers se configuran por scope: local | user | project | enterprise | managed

Adaptación para Cadences: Cada servicio externo (pagos, calendarios, CRMs) = MCP-like server con interfaz estándar tools/resources. InProcessTransport ideal para comunicación entre Workers sin network hops.

3.5 Session/State Management

Ubicación: src/utils/sessionState.ts, sessionStorage.ts, sessionRestore.ts

Arquitectura: JSONL append-only para transcripts, listener pattern para broadcasting de estado.

Session states: idle | running | requires_action

Storage: Ficheros JSONL en ~/.claude/projects/{project-hash}/. Cada línea = mensaje tipado. Append-only con tombstone rewriting para correcciones.

Adaptación para NutriNen:

// IndexedDB con patrón JSONL append-only
const foodLog = {
    entries: [
        { ts: 1712000000, type: 'food_logged', data: { food: 'Banana', calories: 105 } },
        { ts: 1712003600, type: 'meal_complete', data: { meal: 'breakfast', total_cal: 450 } },
    ]
};
// Sync: solo enviar entries nuevas al cloud → conflict-free por diseño

3.6 Config Cascading

Ubicación: src/utils/config.ts, src/utils/settings/

Orden de carga (menor a mayor prioridad):

1. userSettings — ~/.claude/settings.json
2. projectSettings — .claude/settings.json
3. localSettings — .claude/settings.local.json (gitignored)
4. flagSettings — --settings CLI flag
5. policySettings — managed-settings.json + drop-ins managed-settings.d/*.json

Merge strategy: mergeWith() con concatenación de arrays custom. Validación Zod que preserva campos desconocidos para forward compatibility.

Enterprise controls: allowManagedPermissionRulesOnly, strictPluginOnlyCustomization, allowedMcpServers

Adaptación para Cadences: 4 niveles en D1: platform_defaults → org_settings → project_settings → user_preferences. Drop-in pattern para packs de personalización por tenant.

3.7 Telemetry/Analytics

Ubicación: src/utils/telemetry/

Stack: OpenTelemetry completo con traces, metrics, logs.

Span hierarchy: interaction → llm_request → tool → tool.execution

Exporters: OTLP (gRPC, HTTP/JSON, HTTP/protobuf), Prometheus, console, BigQuery custom.

Privacy: redactIfDisabled() — opt-in para contenido de prompts.

Adaptación para Cadences: Workers Analytics Engine o collector OTEL. Spans: user_action → api_call → worker_execution. Pattern redactIfDisabled para GDPR.

3.8 Task/Todo System

Ubicación: src/utils/tasks.ts, src/utils/todo/

Schema:

const TaskSchema = z.object({
    id: z.string(),
    subject: z.string(),
    description: z.string().optional(),
    status: z.enum(['pending', 'in_progress', 'completed']),
    owner: z.string().optional(),
    blocks: z.array(z.string()),      // dependency graph
    blockedBy: z.array(z.string()),
    metadata: z.record(z.unknown()).optional(),
});

Concurrency: File locking con proper-lockfile (30 retries, 5-100ms backoff). High-water mark file para evitar ID reuse.

3.9 Skills System

Ubicación: src/skills/

Arquitectura: Prompt templates con metadata en frontmatter YAML. Múltiples fuentes: bundled | plugin | managed | user | mcp.

Bundled skills: batch, claudeApi, debug, keybindings, loop, remember, verify, stuck, simplify, skillify

Adaptación para Cadences: "Workflow templates" — markdown con frontmatter para acciones, hooks, y parámetros. Almacenados en R2, cargados por tenant.

3.10 Agent Swarm

Ubicación: src/utils/swarm/

Componentes:

• Backends: InProcessBackend, TmuxBackend, ITermBackend
• In-process runner: AsyncLocalStorage-based isolation
• Mailbox: File-based JSON messaging con locking
• Permission sync: Teammates route prompts al leader UI
• Team file: { leadAgentId, members[], teamAllowedPaths[] }

Flujo:

Leader → TeamCreateTool → spawn teammates (tmux/in-process)
       → TaskCreateTool → create tasks with dependencies
       → Teammates poll mailbox → pick tasks → execute → update status
       → Teammates send idle notification on Stop
       → Leader aggregates results

Comparación: Synapse vs Claude Code

Lo que Synapse tiene y Claude Code no

1. ✅ Watchdog de recuperación automática
2. ✅ Autonomía via cron (trabaja sin humano)
3. ✅ Multimodalidad por agente
4. ✅ Synapse Bridge (cross-system events)
5. ✅ UI gamificada con estados emocionales

Lo que Claude Code tiene y Synapse debería adoptar

1. 🎯 Permission delegation granular por tool
2. 🎯 Dependency graph (blocks/blockedBy) vs solo parallel_group
3. 🎯 Approval bridge (Director revisa trabajo antes de publicar)
4. 🎯 AsyncLocalStorage isolation para multi-agent en un Worker
5. 🎯 File locking robusto (30 retries, exponential backoff)

Patrones Cross-Cutting

Roadmap

Fase 1 — Quick Wins (1-2 semanas)

• Config cascading en Cadences — Implementar getEffectiveConfig(tenantId) que merge platform → org → project → user desde D1
• JSONL sync en NutriNen — Migrar food log a append-only pattern en IndexedDB con syncPendingEntries() al cloud

Fase 2 — Core Infrastructure (3-4 semanas)

• Hook System en Cadences — Tabla webhook_configs, Worker executor, Queue async delivery con retry
• Permission rules en Cadences — Tabla permission_rules, evaluator en Workers con deny-first cascade
• Dependency graph en Synapse — Añadir blocks/blockedBy a synapse_task_steps, evaluator de readiness

Fase 3 — Advanced Features (4-6 semanas)

• Plugin Marketplace en Cadences — Manifest schema, R2 storage, installed_integrations table, loader
• Approval bridge en Synapse — Director review workflow antes de output final
• AsyncLocalStorage isolation en Synapse — Multi-agent execution en un solo Worker invocation

Fase 4 — Excellence (ongoing)

• OTel instrumentation — Spans jerárquicos en Cadences Workers
• Skills/Workflow templates — Editor visual de workflows con frontmatter en Cadences

Deep Dives Técnicos

7.1 Tool Execution Pipeline

El corazón de Claude Code — cómo cada tool_use del LLM se convierte en una acción real.

Tool Registration

Pattern estático en tools.ts — getAllBaseTools() retorna un array hardcoded con feature-gating:

export function getAllBaseTools(): Tools {
  return [
    AgentTool, TaskOutputTool, BashTool, GlobTool, GrepTool,
    FileReadTool, FileEditTool, FileWriteTool, WebFetchTool,
    // Feature-gated tools
    ...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : []),
    // Lazy require() to break circular deps
    ...(feature('COORDINATOR_MODE') ? [getTeamCreateTool()] : []),
  ]
}

• assembleToolPool() merge built-in + MCP tools, dedup by name (built-in gana), sort alphabético por partición para prompt cache stability
• Tools deferidos: shouldDefer flag — no aparecen en el prompt inicial, el modelo debe ToolSearch(select:name) primero

Tool Interface (buildTool() factory)

Cada tool es un objeto con defaults fail-closed:

TOOL_DEFAULTS = {
    isEnabled: () => true,
    isConcurrencySafe: () => false,  // ← fail-closed
    isReadOnly: () => false,         // ← assume writes
    isDestructive: () => false,
    checkPermissions: () => ({ behavior: 'allow' }),
}

Métodos clave:

• call(args, context, canUseTool, parentMessage, onProgress) — ejecución
• inputSchema / outputSchema — schemas Zod v4
• description(input, options) — prompt dinámico para el modelo
• checkPermissions(input, context) → PermissionDecision
• validateInput(input, context) — pre-permission validation
• mapToolResultToToolResultBlockParam() — output → API format
• renderToolUseMessage() / renderToolResultMessage() — React/Ink components

Pipeline completo (14 pasos)

LLM tool_use block
  │
  ├─ 1. Zod validation (safeParse)
  ├─ 2. Tool-specific validation (file size < 1 GiB, UNC paths, secrets)
  ├─ 3. Speculative classifier (Bash safety — starts in paralelo)
  ├─ 4. Input backfill (clone para hooks, original para call)
  ├─ 5. PreToolUse hooks (may modify input, stop, attach context)
  ├─ 6. OTel tracing (startToolSpan)
  ├─ 7. Permission resolution (hooks + canUseTool + classifier merge)
  ├─ 8. Permission denied → log + optional PermissionDenied hooks
  ├─ 9. tool.call() ← EJECUCIÓN REAL
  ├─ 10. Result mapping → API ToolResultBlockParam
  ├─ 11. Large result persistence (>maxResultSizeChars → disco, preview 2KB)
  ├─ 12. PostToolUse hooks (may modify MCP output)
  ├─ 13. Append newMessages (sub-agent transcripts)
  └─ 14. Error handling → classifyToolError → formatError → XML wrapper

Concurrencia (StreamingToolExecutor)

• Tools concurrent-safe → ejecutan en paralelo
• Tools non-concurrent → serial exclusivo
• Sibling abort: error en Bash aborta tools hermanos
• Resultados buffered y emitidos en orden del tool_use (no orden de completion)

Error handling patterns

• formatError(): Trunca a 10K chars (5K inicio + 5K final)
• formatZodValidationError(): Mensajes legibles, no raw Zod
• classifyToolError(): Para telemetría — usa errno codes, nunca names minificados
• Empty results → "(toolName completed with no output)" (evita stop-sequence bugs)

💡 Para Cadences: El buildTool() factory con defaults fail-closed es directamente reutilizable para definir acciones de API. El pipeline de 14 pasos es un modelo para cualquier sistema de ejecución de acciones con middleware.

7.2 MCP Implementation Details

Model Context Protocol — cómo Claude Code conecta con servidores de herramientas externos.

Server Discovery (multi-scope)

Config scopes (por prioridad):

1. local — .mcp.json en el directorio de trabajo
2. user — config global de usuario
3. project — settings de proyecto
4. dynamic — inyectado en runtime (IDE extensions)
5. enterprise — managed-mcp.json
6. claudeai — servers proxiados via claude.ai
7. managed — servers del sistema

Transportes soportados

Connection Lifecycle

Config → Transport creation → Client connect (30s timeout)
  → Extract capabilities, serverVersion, instructions (max 2048 chars)
  → Register elicitation handler + cleanup callbacks
  
On error (3+ consecutive terminal errors: ECONNRESET, ETIMEDOUT, EPIPE):
  → closeTransportAndRejectPending → reject all pending tool promises
  → Clear caches → Fresh connection next call

On session expiry (HTTP 404 + JSON-RPC -32001):
  → Close transport → Retry once with fresh client

Cleanup (stdio): SIGINT → 100ms → SIGTERM → 400ms → SIGKILL → 600ms

Tool Naming Convention

MCP tools se exponen al modelo como: mcp__{normalizedServerName}__{toolName}

• Description capped a 2048 chars
• Annotations: readOnlyHint, destructiveHint, openWorldHint
• Output limit: 25,000 tokens (configurable), oversized → disco + preview

Reconnection con exponential backoff

MAX_RECONNECT_ATTEMPTS = 5, INITIAL_BACKOFF_MS = 1000, MAX_BACKOFF_MS = 30000

Batching

• Local servers (stdio/sdk): batchSize = 3 (evita fork-bomb)
• Remote servers: batchSize = 20 (network I/O bound)

💡 Para Cadences: El patrón MCP es ideal para integrar servicios externos (Stripe, Google Calendar, CRMs) como "servidores de herramientas" con interfaz estándar. El multi-transport approach permite conectar vía HTTP a APIs externas y vía in-process a servicios internos en Workers.

7.3 Context Window Management

Token Budget

Capped default optimization: CAPPED_DEFAULT_MAX_TOKENS = 8,000 para no reservar de más. Si se alcanza → retry con ESCALATED_MAX_TOKENS = 64,000.

Token Counting

• Primario: Lee usage de la response API (input + cache_creation + cache_read + output)
• Fallback: roughTokenCountEstimationForMessages() basado en JSON.stringify length
• Analysis: analyzeContext() categoriza tokens por: tool requests (por nombre), tool results, human/assistant messages, attachments, duplicate file reads (waste tracking)

System Prompt Assembly

STATIC (prompt cache global):
  ├─ Intro (identidad, URL guardrails)
  ├─ System (output format, permissions model)
  ├─ Doing Tasks (coding philosophy, security)
  ├─ Actions (blast-radius, confirmations)
  ├─ Using Tools (parallel calls, task management)
  ├─ Tone & Style (no emojis, concise)
  └─ Output Efficiency (inverted pyramid)

── DYNAMIC BOUNDARY ──

DYNAMIC (per-session):
  ├─ Session guidance (agent tool instructions)
  ├─ Memory (CLAUDE.md files)
  ├─ Environment info (CWD, git, platform, model)
  ├─ MCP instructions (server-provided)
  ├─ Token budget ("+500k" style)
  └─ Custom system prompt overrides

Split at __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ → antes = scope: 'global' cache, después = per-session.

Context Collapse

• UI collapse: Read/Search/Grep sequences agrupadas en CollapsedReadSearchGroup
• Function Result Clearing: Old tool results se limpian, manteniendo los N más recientes
• MCP output truncation: Cap 25K tokens → disco + preview
• MCP Instructions Delta: Entrega incremental de instrucciones (solo servers nuevos/desconectados)

User Token Budgets

El usuario puede pedir: +500k, +2M, +1B tokens. El sistema auto-continúa hasta alcanzar el budget.

💡 Para Cadences: El patrón de split estático/dinámico del system prompt es reutilizable para caching de prompts en la API de Anthropic. El context analysis para tracking de "waste" (reads duplicados) es útil para optimizar costos de API.

7.4 React/Ink Terminal UI

Component Architecture

App (providers)
  └── FullscreenLayout
        ├── ScrollBox (virtualized, only renders visible rows)
        │     ├── LogoV2 + StatusNotices (memo'd header)
        │     ├── Messages (normalize → collapse → group → render)
        │     │     └── MessageRow → Message → type-dispatched:
        │     │           assistant → TextMessage | ThinkingMessage | ToolUseMessage
        │     │           user → TextMessage | ImageMessage | ToolResultMessage  
        │     │           system → SystemTextMessage
        │     │           collapsed_read_search → CollapsedReadSearchContent
        │     └── PermissionRequest overlay
        ├── Spinner + PromptInput + permissions (bottom)
        ├── Modal (slash-command dialogs)
        └── CompanionSpeechBubble (bottomFloat)

Performance Patterns

• React Compiler: Auto-memoización de component trees (_c() cache slots)
• OffscreenFreeze: Previene re-renders de contenido fuera de pantalla (crítico para sesiones de 2800+ mensajes)
• Virtual scrolling: Solo renderiza filas visibles
• "N new messages" pill: useSyncExternalStore para scroll tracking sin re-renders

Input: Emacs + Vim

• Emacs mode: Kill ring (Ctrl-K/U/W + Ctrl-Y yank), word/line movement, image paste detection
• Vim mode: State machine completa con 11 estados (idle → count → operator → operatorFind → ...), dot-repeat, registers, find motions
• Vim transitions son pure functions: transition(state, input, ctx) → { next?, execute? } — nunca side-effects y state al mismo tiempo

Theme System (70+ semantic colors)

6 temas: dark, light, dark-ansi, light-ansi, dark-daltonized, light-daltonized

Colores organizados por propósito: core UI, semantic (success/error/warning), diff, agents (8 colores con _FOR_SUBAGENTS_ONLY), shimmer variants para animaciones, rainbow (7 colores para "ultrathink" highlighting).

• RGB themes: rgb(r,g,b) explícito (evita inconsistencias de paletas ANSI custom)
• ANSI themes: ansi:colorName para terminales sin truecolor

💡 Para Cadences: El patrón de theming con 70+ semantic colors + daltonized variants es un modelo para accesibilidad. El virtual scrolling con OffscreenFreeze es reutilizable en cualquier lista larga (feeds, logs, chat).

7.5 Auth & Security Patterns

Multi-Source Auth (priority ordering)

1. ANTHROPIC_AUTH_TOKEN env var
2. CLAUDE_CODE_OAUTH_TOKEN env var (CCR/Desktop) 
3. File Descriptor OAuth (pipe FD from Go env-manager)
4. CCR well-known file (/home/claude/.claude/remote/.oauth_token)
5. apiKeyHelper (external command from settings)
6. Claude.ai OAuth (keychain)
7. none

Managed OAuth isolation: Cuando Claude corre en CCR/Desktop, NUNCA consulta settings del terminal del usuario → previene key leakage cross-org.

Secure Storage

macOS → KeychainStorage → FallbackStorage → PlainTextStorage
Linux → PlainTextStorage (~/.claude/.credentials.json)

Keychain: hex-encoded payloads via security -i stdin (no argv → oculto de process monitors como CrowdStrike). Stale-while-error cache — si el keychain falla, sirve data cacheada en vez de null.

API keys: solo se almacenan los últimos 20 caracteres (suficiente para identificación sin exposición completa).

Input Sanitization (anti-injection)

Mitigación de ataques Unicode (HackerOne #3086545):

1. NFKC normalization
2. Strip [\p{Cf}\p{Co}\p{Cn}] (format controls, private use, unassigned)
3. Strip zero-width spaces, directional formatting, BOM
4. Loop hasta convergencia (max 10 iterations)
5. Variante recursiva para objects/arrays

Privacy Levels

💡 Para Cadences: El patrón de sanitización Unicode es CRÍTICO para cualquier app que reciba input de usuarios. Los 3 privacy levels mapean directamente a tiers de GDPR compliance. El stale-while-error cache pattern es reutilizable para cualquier storage que pueda fallar transientemente.

7.6 Bash Safety & Parsing

Anti-Injection Defenses

• Random-salted placeholders: randomBytes(8).toString('hex') como salt → previene inyección donde comandos contienen strings de placeholder
• Static redirect validation: Rechaza targets con whitespace, quotes, $, backticks, globs, brace expansion, ~, process substitution, history expansion (!)
• Line continuation: Solo join en número impar de backslashes (par = escape paired)
• Parser differential hardening: Rechaza targets con # para cerrar diferencial shell-quote/bash
• Heredoc pre-processing: << blocks procesados antes del parser (que los manejaba mal)

Dangerous Patterns

Dos listas para limpiar allow rules overly-permissive:

Code execution: python, node, deno, tsx, ruby, perl, php, lua, npx, bunx, npm run, yarn run, bash, sh, ssh

Bash-specific: zsh, fish, eval, exec, env, xargs, sudo

Internal-only (behind USER_TYPE === 'ant'): curl, wget, git, kubectl, aws, gcloud

💡 Para Cadences: Las listas de dangerous patterns son directamente reutilizables si Cadences alguna vez permite ejecución de scripts por tenants. El patrón de static redirect validation aplica a cualquier sistema que genere shell commands (deploy scripts, CI/CD).

Conclusiones Clave

Lo más valioso para CadencesLab

1. buildTool() factory con defaults fail-closed — Todo nuevo tool/action es deny-by-default hasta que opt-in explícito. Previene fallos de seguridad por omisión.

2. 14-step execution pipeline — Modelo probado para cualquier sistema que ejecute acciones: validate → hook → permission → execute → format → persist. Cada paso es un middleware independiente.

3. MCP multi-transport — Arquitectura para integrar N servicios externos con interfaz unificada. Transportes intercambiables (HTTP, WS, in-process).

4. Prompt cache stability — Sort tools alfabéticamente, split system prompt en static/dynamic boundary, deferred tool loading. Reduce costos de API significativamente.

5. Unicode sanitization — Obligatorio para cualquier app que reciba input de usuarios. Multi-pass iterativo hasta convergencia.

6. Stale-while-error pattern — Para keychain, D1, KV, o cualquier storage que pueda fallar. Sirve data stale en vez de error.

7. Context analysis (waste tracking) — Trackear reads duplicados, tokens por categoría. Permite optimizar costos de API proactivamente.

8. Privacy levels (3-tier) — Mapea directamente a GDPR tiers. Simple de implementar, big compliance win.

Documento mantenido por CadencesLab — Anthropic Partner
Fuente: experimental/AnthropicsClaudeCode/src/
Última actualización: Abril 2026