Dokumentasi settings.json

Cakupan. Dokumen ini menjelaskan file pengabelan hook (settings.json) milik adapter Claude Code. harness lain menggunakan permukaan pengaturan native masing-masing — lihat site/content/docs/harnesses/<harness>.mdx untuk titik masuk konfigurasi setara dari setiap adapter.

Ikhtisar

settings.json mengonfigurasi eksekusi hook Claude Code untuk ekosistem Apothem. File ini mendeklarasikan hook mana yang berjalan pada event mana, timeout-nya, dan permukaan izin tingkat atas. Apothem mengirimkan satu template kanonis karena Claude Code memuat ~/.claude/settings.json di semua platform yang didukung.

Runtime Khusus Python

Setiap hook yang dikonfigurasi menggunakan bentuk perintah exec Claude Code. Template yang dikirimkan membawa token ${HARNESS_ROOT}:

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

apothem install merender token tersebut menjadi jalur absolut akar harness (bentuk garis miring depan, valid di Windows, macOS, dan Linux), sehingga settings.json yang terpasang memanggil dispatcher yang dimaterialisasi di ~/.claude/.apothem/support/hooks/dispatch.py secara langsung. Dispatcher dan gerbang konformitas (~/.claude/.apothem/support/conformity/gate.py, dengan fixture schema-nya di sebelahnya pada ~/.claude/.apothem/support/schemas/) adalah skrip stdlib mandiri — tidak diperlukan paket apothem yang dapat diimpor di host, dan satu template melayani setiap platform.

Schema Konfigurasi Hook

Izin

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

Tool yang tidak ada di allow memerlukan persetujuan eksplisit per-panggilan atau izin tingkat workspace. Tool read-only sudah disetujui sebelumnya; operasi tulis (Write, Edit, NotebookEdit, Bash) berjalan melalui validator PreToolUse.

Event Hook

Nilai timeout mencerminkan anggaran hook-event kanonis — tabel di bawah mereproduksinya demi kemudahan pembaca; sumber kanonis yang berlaku.

dispatch.py juga menerima UserPromptSubmit dan Notification pada daftar putih event-nya. Tidak satu pun yang dikabelkan di template yang dikirimkan; tambahkan blok matcher dengan pola locator + dispatch yang sama untuk mengaktifkannya.

Field Tingkat Atas

Validasi

Tiga validator mencakup permukaan hook, dengan kerigoran yang meningkat:

# Struktural + higiene Python (cepat, offline)
python scripts/dev/validate_hooks.py

# Ekosistem penuh (struktur + frontmatter + pemeriksaan hook yang didelegasikan)
python scripts/dev/validate_ecosystem.py

# Sapuan adversarial (menyerang setiap perintah hook yang dikonfigurasi dengan input terdegradasi)
python scripts/dev/chaos_pass.py

Ketiganya harus keluar dengan 0 sebelum melakukan commit perubahan hook atau pengaturan.

Uji asap ad-hoc dari satu event:

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

Keluaran yang diharapkan: amplop JSON satu baris yang berisi hookSpecificOutput.

Masalah Umum

SessionStart timeout

Paling umum, locator find-python menemukan shim Microsoft Store dan gagal menyelesaikan interpreter sungguhan. Verifikasi:

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

Jika perintah mencetak amplop JSON yang valid tetapi panel Claude Code menampilkan timeout, naikkan timeout event tersebut di settings.json. Jika perintah gagal di tingkat shell, pasang CPython 3.10+ sungguhan dan pastikan ia ada di PATH atau dapat ditemukan oleh locator.

Setiap Write/Edit terblokir

PreToolUse menandai istilah internal plan dalam konten yang ditulis di luar akar pemasangan harness (~/.claude/ untuk adapter Claude Code). Tinjau konten untuk pelanggaran CM-7 (lihat src/apothem/rules/persistent-conventions-vigilance.md). Hanya bahasa domain untuk artefak basis kode.

settings.json tidak dimuat

Claude Code membaca ~/.claude/settings.json. Verifikasi Apothem terpasang ke akar harness yang diharapkan dan mulai ulang sesi setelah mengubah file.

Hook diam-diam tidak melakukan apa-apa

Kontrak hook adalah "selalu keluar dengan 0, selalu memancarkan JSON yang valid". Jika interpreter tidak dapat ditemukan, locator mengembalikan kosong dan perintah menjadi no-op. Jalankan chaos_pass.py untuk memastikan setiap hook yang dikonfigurasi mengembalikan amplop yang valid — ia menangkap jalur resolusi terdegradasi yang akan disembunyikan oleh sesi langsung.

Presedensi Berlapis

Claude Code menyelesaikan objek pengaturan efektif dengan menyusun tiga lapisan dalam urutan presedensi yang meningkat:

Nilai tingkat lebih tinggi mengesampingkan nilai tingkat lebih rendah pada tingkat kunci-daun — ketika baik lapisan proyek maupun lokal-pengguna mendeklarasikan entri permissions.allow, gabungan diambil; ketika keduanya mendeklarasikan skalar seperti theme, nilai lokal-pengguna menang. Semantik penggabungan per-kunci yang tepat dimiliki oleh harness Claude Code.

Membuat override lokal-pengguna

1. Salin settings.local.example.json (akar repositori) ke <harness-root>/settings.local.json. Nama file settings.local.json cocok dengan pola .gitignore, sehingga file tidak pernah masuk ke kontrol versi.
2. Edit salinan lokal — simpan hanya kunci yang akan di-override; harness menyusun lapisan-lapisan, sehingga kunci yang tidak ada diwarisi dari lapisan proyek.
3. Verifikasi file terurai sebagai JSON yang valid sebelum menyimpan — harness menolak JSON yang malformed saat sesi dimulai.