Documentation de settings.json

Portée. Ce document décrit le fichier de câblage des hooks (settings.json) de l'adaptateur Claude Code. Les autres harness utilisent leurs propres surfaces de réglages natives — voir site/content/docs/harnesses/<harness>.mdx pour le point d'entrée de configuration équivalent de chaque adaptateur.

Vue d'ensemble

settings.json configure l'exécution des hooks de Claude Code pour l'écosystème Apothem. Il déclare quels hooks se déclenchent sur quels événements, leurs délais d'attente et la surface de permissions de premier niveau. Apothem livre un seul modèle canonique parce que Claude Code charge ~/.claude/settings.json sur toutes les plateformes prises en charge.

Runtime Python uniquement

Chaque hook configuré utilise la forme de commande exec de Claude Code. Le modèle livré porte le jeton ${HARNESS_ROOT} :

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

apothem install rend le jeton sous la forme du chemin absolu de la racine du harness (forme avec barre oblique, valide sous Windows, macOS et Linux), de sorte que le settings.json installé invoque directement le répartiteur matérialisé à ~/.claude/.apothem/support/hooks/dispatch.py. Le répartiteur et la porte de conformité (~/.claude/.apothem/support/conformity/gate.py, avec ses fixtures de schéma à ses côtés à ~/.claude/.apothem/support/schemas/) sont des scripts autonomes de la bibliothèque standard — aucun paquet apothem importable n'est requis sur l'hôte, et un seul modèle sert chaque plateforme.

Schéma de configuration des hooks

Permissions

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

Les outils absents de allow requièrent une approbation explicite par appel ou une permission au niveau de l'espace de travail. Les outils en lecture seule sont préapprouvés ; les opérations d'écriture (Write, Edit, NotebookEdit, Bash) passent par le validateur PreToolUse.

Événements de hooks

Les valeurs de délai d'attente reflètent les budgets canoniques des événements de hook — le tableau ci-dessous les reproduit pour la commodité du lecteur ; la source canonique fait foi.

dispatch.py accepte en outre UserPromptSubmit et Notification dans sa liste blanche d'événements. Aucun n'est câblé dans les modèles livrés ; ajoutez un bloc matcher avec le même motif de localisateur + répartition pour l'activer.

Champs de premier niveau

Validation

Trois validateurs couvrent la surface des hooks, par rigueur croissante :

# Structurel + hygiène Python (rapide, hors ligne)
python scripts/dev/validate_hooks.py

# Écosystème complet (structure + frontmatter + vérifications de hooks déléguées)
python scripts/dev/validate_ecosystem.py

# Balayage adversarial (assaille chaque commande de hook configurée avec des entrées dégradées)
python scripts/dev/chaos_pass.py

Les trois doivent sortir avec 0 avant de valider des changements de hooks ou de réglages.

Test de fumée ad hoc d'un seul événement :

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

Sortie attendue : une enveloppe JSON sur une seule ligne contenant hookSpecificOutput.

Problèmes courants

SessionStart dépasse le délai d'attente

Le plus souvent, le localisateur find-python découvre le shim Microsoft Store et échoue à résoudre un interpréteur réel. Vérifiez :

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

Si la commande affiche une enveloppe JSON valide mais que le panneau Claude Code montre un dépassement de délai, augmentez le timeout de l'événement dans settings.json. Si la commande échoue au niveau du shell, installez un CPython 3.10+ réel et assurez-vous qu'il est sur le PATH ou détectable par le localisateur.

Chaque Write/Edit est bloqué

PreToolUse signale des termes internes au plan dans du contenu écrit en dehors de la racine d'installation du harness (~/.claude/ pour l'adaptateur Claude Code). Examinez le contenu à la recherche de violations CM-7 (voir src/apothem/rules/persistent-conventions-vigilance.md). Langage de domaine uniquement pour les artefacts de la base de code.

settings.json non chargé

Claude Code lit ~/.claude/settings.json. Vérifiez qu'Apothem est installé dans la racine du harness attendue et redémarrez la session après avoir modifié le fichier.

Les hooks ne font silencieusement rien

Le contrat d'un hook est « toujours sortir avec 0, toujours émettre du JSON valide ». Si l'interpréteur ne peut être localisé, le localisateur renvoie du vide et la commande devient une non-opération. Exécutez chaos_pass.py pour confirmer que chaque hook configuré renvoie une enveloppe valide — il détecte les chemins de résolution dégradés qu'une session en direct masquerait.

Précédence en couches

Claude Code résout l'objet de réglages effectif en composant trois couches par ordre croissant de précédence :

Les valeurs de niveau supérieur surchargent les valeurs de niveau inférieur au niveau de la clé-feuille — lorsque les couches projet et local utilisateur déclarent toutes deux une entrée permissions.allow, l'union est prise ; lorsque toutes deux déclarent un scalaire comme theme, la valeur local utilisateur l'emporte. La sémantique exacte de fusion par clé appartient au harness Claude Code.

Créer une surcharge local utilisateur

1. Copiez settings.local.example.json (racine du dépôt) vers <harness-root>/settings.local.json. Le nom de fichier settings.local.json correspond au motif de .gitignore, de sorte que le fichier n'atterrit jamais dans le contrôle de version.
2. Modifiez la copie locale — ne gardez que les clés à surcharger ; le harness compose les couches, donc les clés absentes héritent de la couche projet.
3. Vérifiez que le fichier s'analyse comme du JSON valide avant de l'enregistrer — le harness rejette le JSON malformé au démarrage de la session.