Documentación de settings.json

Alcance. Este documento describe el archivo de cableado de hooks (settings.json) del adaptador de Claude Code. Otros entornos usan sus propias superficies de ajustes nativas — consulta site/content/docs/harnesses/<harness>.mdx para conocer el punto de entrada de configuración equivalente de cada adaptador.

Visión generalCopy Anchor Link

settings.json configura la ejecución de hooks de Claude Code para el ecosistema Apothem. Declara qué hooks se disparan en qué eventos, sus tiempos de espera y la superficie de permisos de nivel superior. Apothem distribuye una única plantilla canónica porque Claude Code carga ~/.claude/settings.json en todas las plataformas compatibles.

Runtime solo PythonCopy Anchor Link

Cada hook configurado usa la forma de comando exec de Claude Code. La plantilla distribuida lleva los tokens ${PYTHON_BIN} y ${HARNESS_ROOT}; apothem install sustituye ${PYTHON_BIN} por el intérprete absoluto resuelto:

{
  "type": "command",
  "command": "${PYTHON_BIN}",
  "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "PreToolUse", "pretooluse-write"]
}

apothem install renderiza el token a la ruta absoluta de la raíz del entorno (forma con barra diagonal, válida en Windows, macOS y Linux), de modo que el settings.json instalado invoca directamente el despachador materializado en ~/.claude/.apothem/support/hooks/dispatch.py. El despachador y la puerta de conformidad (~/.claude/.apothem/support/conformity/gate.py, con sus fixtures de schema junto a él en ~/.claude/.apothem/support/schemas/) son scripts autónomos de la biblioteca estándar — no se requiere ningún paquete apothem importable en el host, y una sola plantilla sirve para cada plataforma.

Esquema de configuración de hooksCopy Anchor Link

PermisosCopy Anchor Link

"permissions": {
  "allow": ["Read", "Glob", "Grep"]
}

Las herramientas que no están en allow requieren aprobación explícita por llamada o permiso a nivel de espacio de trabajo. Las herramientas de solo lectura están preaprobadas; las operaciones de escritura (Write, Edit, NotebookEdit, Bash) pasan por el validador PreToolUse.

Eventos de hooksCopy Anchor Link

Los valores de tiempo de espera reflejan los presupuestos canónicos de eventos de hook — la tabla a continuación los reproduce para comodidad del lector; la fuente canónica prevalece.

Esta plantilla registra cuatro eventos. No registra PreCompact ni PostCompact; sí lo hacen las plantillas de Codex y de Qwen Code, y la referencia de hooks los enumera por entorno.

dispatch.py acepta además UserPromptSubmit y Notification en su lista blanca de eventos. Ninguno está cableado en las plantillas distribuidas; añade un bloque matcher con el mismo patrón de localizador + despacho para habilitarlo.

Campos de nivel superiorCopy Anchor Link

ValidaciónCopy Anchor Link

Tres validadores cubren la superficie de hooks, con rigor creciente:

# Estructural + higiene de Python (rápido, offline)
python scripts/dev/validate_hooks.py

# Ecosistema completo (estructura + frontmatter + comprobaciones de hooks delegadas)
python scripts/dev/validate_ecosystem.py

# Barrido adversarial (azota cada comando de hook configurado con entradas degradadas)
python scripts/dev/chaos_pass.py

Los tres deben salir con 0 antes de hacer commit de cambios en hooks o ajustes.

Prueba de humo ad-hoc de un solo evento:

python src/apothem/hooks/dispatch.py --event-name SessionStart

Salida esperada: un sobre JSON de una sola línea que contiene hookSpecificOutput.

Problemas comunesCopy Anchor Link

SessionStart agota el tiempo de esperaCopy Anchor Link

Lo más común es que el localizador find-python esté descubriendo el shim de Microsoft Store y no logre resolver un intérprete real. Verifica:

python src/apothem/hooks/dispatch.py --event-name SessionStart

Si el comando imprime un sobre JSON válido pero el panel de Claude Code muestra un tiempo de espera agotado, aumenta el timeout del evento en settings.json. Si el comando falla a nivel de shell, instala un CPython 3.10+ real y asegúrate de que esté en el PATH o sea descubrible por el localizador.

Cada Write/Edit queda bloqueadoCopy Anchor Link

PreToolUse está marcando términos internos de plan en contenido que se escribe fuera de la raíz de instalación del entorno (~/.claude/ para el adaptador de Claude Code). Revisa el contenido en busca de violaciones de CM-7 (ver src/apothem/rules/persistent-conventions-vigilance.md). Solo lenguaje de dominio para los artefactos del código base.

settings.json no se cargaCopy Anchor Link

Claude Code lee ~/.claude/settings.json. Verifica que Apothem se instaló en la raíz del entorno esperada y reinicia la sesión después de cambiar el archivo.

Los hooks no hacen nada en silencioCopy Anchor Link

El contrato de un hook es "siempre salir con 0, siempre emitir JSON válido". Si no se puede localizar el intérprete, el localizador devuelve vacío y el comando se convierte en una no-operación. Ejecuta chaos_pass.py para confirmar que cada hook configurado devuelve un sobre válido — captura las rutas de resolución degradadas que una sesión en vivo ocultaría.

Precedencia por capasCopy Anchor Link

Claude Code resuelve el objeto de ajustes efectivo componiendo tres capas en orden creciente de precedencia:

Los valores de nivel superior anulan los de nivel inferior a nivel de clave hoja — cuando tanto la capa de proyecto como la local de usuario declaran una entrada permissions.allow, se toma la unión; cuando ambas declaran un escalar como theme, gana el valor local de usuario. La semántica exacta de fusión por clave es propiedad del entorno de Claude Code.

Crear una anulación local de usuarioCopy Anchor Link

1. Copia examples/harnesses/claude-code/settings.local.example.json a <harness-root>/settings.local.json. El nombre de archivo settings.local.json coincide con el patrón de .gitignore, así que el archivo nunca llega al control de versiones.
2. Edita la copia local: conserva solo las claves que quieras anular. El entorno compone las capas, así que las claves ausentes heredan de la capa de proyecto.
3. Verifica que el archivo se analiza como JSON válido antes de guardarlo. El entorno rechaza el JSON mal formado al iniciar la sesión.