settings.json-Dokumentation

Geltungsbereich. Dieses Dokument beschreibt die Hook-Verdrahtungsdatei (settings.json) des Claude Code Adapters. Andere harness verwenden ihre eigenen nativen Einstellungsoberflächen — siehe site/content/docs/harnesses/<harness>.mdx für den äquivalenten Konfigurations-Einstiegspunkt jedes Adapters.

ÜberblickCopy Anchor Link

settings.json konfiguriert die Hook-Ausführung von Claude Code für das Apothem-Ökosystem. Sie deklariert, welche Hooks bei welchen Ereignissen auslösen, ihre Timeouts und die Berechtigungsoberfläche der obersten Ebene. Apothem liefert eine einzige kanonische Vorlage aus, weil Claude Code ~/.claude/settings.json auf allen unterstützten Plattformen lädt.

Reine Python-LaufzeitCopy Anchor Link

Jeder konfigurierte Hook verwendet die Exec-Befehlsform von Claude Code. Die ausgelieferte Vorlage trägt die Token ${PYTHON_BIN} und ${HARNESS_ROOT}; apothem install ersetzt ${PYTHON_BIN} durch den aufgelösten absoluten Interpreter:

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

apothem install rendert das Token zum absoluten Pfad der harness-Wurzel (Schrägstrich-Form, gültig unter Windows, macOS und Linux), sodass die installierte settings.json den unter ~/.claude/.apothem/support/hooks/dispatch.py materialisierten Dispatcher direkt aufruft. Der Dispatcher und das Konformitäts-Gate (~/.claude/.apothem/support/conformity/gate.py, mit seinen Schema-Fixtures daneben unter ~/.claude/.apothem/support/schemas/) sind eigenständige Standardbibliotheks-Skripte — auf dem Host wird kein importierbares apothem-Paket benötigt, und eine einzige Vorlage bedient jede Plattform.

Hook-KonfigurationsschemaCopy Anchor Link

BerechtigungenCopy Anchor Link

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

Werkzeuge, die nicht in allow stehen, erfordern eine explizite Genehmigung pro Aufruf oder eine Berechtigung auf Arbeitsbereichsebene. Nur-Lese-Werkzeuge sind vorab genehmigt; Schreiboperationen (Write, Edit, NotebookEdit, Bash) durchlaufen den PreToolUse-Validator.

Hook-EreignisseCopy Anchor Link

Die Timeout-Werte spiegeln die kanonischen Hook-Ereignis-Budgets wider — die Tabelle unten reproduziert sie zur Bequemlichkeit des Lesers; die kanonische Quelle ist maßgeblich.

Diese Vorlage registriert vier Ereignisse. Sie registriert weder PreCompact noch PostCompact; die Vorlagen für Codex und Qwen Code tun dies, und die Hook-Referenz listet sie je Harness auf.

dispatch.py akzeptiert zusätzlich UserPromptSubmit und Notification auf seiner Ereignis-Whitelist. Keines davon ist in den ausgelieferten Vorlagen verdrahtet; fügen Sie einen Matcher-Block mit demselben Lokalisierer- + Dispatch-Muster hinzu, um es zu aktivieren.

Felder der obersten EbeneCopy Anchor Link

ValidierungCopy Anchor Link

Drei Validatoren decken die Hook-Oberfläche mit zunehmender Strenge ab:

# Strukturell + Python-Hygiene (schnell, offline)
python scripts/dev/validate_hooks.py

# Vollständiges Ökosystem (Struktur + Frontmatter + delegierte Hook-Prüfungen)
python scripts/dev/validate_ecosystem.py

# Adversarialer Durchlauf (überflutet jeden konfigurierten Hook-Befehl mit degradierten Eingaben)
python scripts/dev/chaos_pass.py

Alle drei müssen mit 0 beenden, bevor Hook- oder Einstellungsänderungen committet werden.

Ad-hoc-Rauchtest eines einzelnen Ereignisses:

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

Erwartete Ausgabe: ein einzeiliger JSON-Umschlag, der hookSpecificOutput enthält.

Häufige ProblemeCopy Anchor Link

SessionStart läuft in ein TimeoutCopy Anchor Link

Am häufigsten entdeckt der find-python-Lokalisierer den Microsoft-Store-Shim und scheitert daran, einen echten Interpreter aufzulösen. Überprüfen Sie:

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

Wenn der Befehl einen gültigen JSON-Umschlag ausgibt, das Claude Code Panel aber ein Timeout zeigt, erhöhen Sie das timeout des Ereignisses in settings.json. Wenn der Befehl auf Shell-Ebene fehlschlägt, installieren Sie ein echtes CPython 3.10+ und stellen Sie sicher, dass es im PATH steht oder vom Lokalisierer auffindbar ist.

Jedes Write/Edit wird blockiertCopy Anchor Link

PreToolUse markiert planinterne Begriffe in Inhalten, die außerhalb der harness-Installationswurzel geschrieben werden (~/.claude/ für den Claude Code Adapter). Überprüfen Sie den Inhalt auf CM-7-Verstöße (siehe src/apothem/rules/persistent-conventions-vigilance.md). Nur Domänensprache für Codebasis-Artefakte.

settings.json wird nicht geladenCopy Anchor Link

Claude Code liest ~/.claude/settings.json. Überprüfen Sie, ob Apothem in die erwartete harness-Wurzel installiert wurde, und starten Sie die Sitzung nach dem Ändern der Datei neu.

Hooks tun stillschweigend nichtsCopy Anchor Link

Der Hook-Vertrag lautet „immer mit 0 beenden, immer gültiges JSON ausgeben". Wenn der Interpreter nicht lokalisiert werden kann, gibt der Lokalisierer leer zurück und der Befehl wird zur No-Op. Führen Sie chaos_pass.py aus, um zu bestätigen, dass jeder konfigurierte Hook einen gültigen Umschlag zurückgibt — es fängt degradierte Auflösungspfade ab, die eine Live-Sitzung verbergen würde.

Geschichtete PräzedenzCopy Anchor Link

Claude Code löst das effektive Einstellungsobjekt auf, indem es drei Schichten in aufsteigender Präzedenzordnung zusammensetzt:

Werte höherer Stufe überschreiben Werte niedrigerer Stufe auf Blattschlüssel-Ebene — wenn sowohl die Projekt- als auch die Benutzerlokal-Schicht einen permissions.allow-Eintrag deklarieren, wird die Vereinigung gebildet; wenn beide einen Skalar wie theme deklarieren, gewinnt der benutzerlokale Wert. Die exakte Zusammenführungssemantik pro Schlüssel gehört dem Claude Code harness.

Eine benutzerlokale Überschreibung erstellenCopy Anchor Link

1. Kopieren Sie examples/harnesses/claude-code/settings.local.example.json nach <harness-root>/settings.local.json. Der Dateiname settings.local.json passt zum Muster in .gitignore, sodass die Datei nie in der Versionskontrolle landet.
2. Bearbeiten Sie die lokale Kopie: Behalten Sie nur die Schlüssel, die Sie überschreiben sollen; der Harness setzt die Schichten zusammen, sodass fehlende Schlüssel von der Projektschicht erben.
3. Prüfen Sie vor dem Speichern, ob die Datei als gültiges JSON geparst wird. Der Harness lehnt fehlerhaftes JSON beim Sitzungsstart ab.