settings.json ドキュメント

対象範囲。 本ドキュメントは Claude Code アダプター のフック 配線ファイル（settings.json）について説明します。他のハーネスは それぞれ独自のネイティブ設定面を使用します — 各アダプターの等価な 構成エントリーポイントについては site/content/docs/harnesses/<harness>.mdx を参照してください。

概要Copy Anchor Link

settings.json は、Apothem エコシステム向けに Claude Code のフック実行を構成します。 どのフックがどのイベントで発火するか、それらのタイムアウト、およびトップレベルの 権限面を宣言します。Claude Code はサポート対象の全プラットフォームで ~/.claude/settings.json を読み込むため、Apothem は単一の正規テンプレートのみを同梱します。

Python 専用ランタイムCopy Anchor Link

設定されたフックはすべて、Claude Code の exec 形式のコマンド構造を使います。同梱のテンプレートは ${PYTHON_BIN} と ${HARNESS_ROOT} のトークンを保持します。apothem install は、${PYTHON_BIN} を解決済みの絶対パスのインタープリターに置き換えます。

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

apothem install はこのトークンをハーネスルートの絶対パス （フォワードスラッシュ形式。Windows・macOS・Linux で有効）にレンダリングするため、 インストール済みの settings.json は ~/.claude/.apothem/support/hooks/dispatch.py に マテリアライズされたディスパッチャを直接呼び出します。ディスパッチャと コンフォーミティゲート（~/.claude/.apothem/support/conformity/gate.py。その schema フィクスチャは隣の ~/.claude/.apothem/support/schemas/ にあります）は、いずれも標準ライブラリ のスタンドアロンスクリプトです — ホスト上にインポート可能な apothem パッケージは不要で、 1 つのテンプレートがすべてのプラットフォームに対応します。

フック構成スキーマCopy Anchor Link

権限Copy Anchor Link

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

allow にないツールは、呼び出しごとの明示的な承認、またはワークスペースレベルの権限を必要とします。 読み取り専用ツールは事前承認されています。書き込み操作（Write、Edit、NotebookEdit、 Bash）は PreToolUse バリデータを通過します。

フックイベントCopy Anchor Link

タイムアウト値は正規のフックイベント予算を反映します — 下表は 読者の便宜のために再掲したものです。正規のソースが支配します。

このテンプレートは 4 つのイベントを登録します。PreCompact と PostCompact は登録しません。Codex と Qwen Code のテンプレートはこれらを登録し、フックリファレンス では、これらをハーネスごとに一覧しています。

dispatch.py はイベントホワイトリストに UserPromptSubmit と Notification も 追加で受け付けます。いずれも同梱テンプレートでは配線されていません。同じ ロケーター + ディスパッチパターンの matcher ブロックを追加すると有効化できます。

トップレベルフィールドCopy Anchor Link

検証Copy Anchor Link

3 つのバリデータが、厳格さを増しながらフック面をカバーします。

# 構造 + Python 衛生（高速・オフライン）
python scripts/dev/validate_hooks.py

# エコシステム全体（構造 + frontmatter + 委譲フックチェック）
python scripts/dev/validate_ecosystem.py

# 敵対的スイープ（構成済みの各フックコマンドを劣化した入力で攻撃）
python scripts/dev/chaos_pass.py

フックまたは設定の変更をコミットする前に、3 つすべてが 0 で終了する必要があります。

単一イベントのアドホックなスモークテスト：

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

期待される出力：hookSpecificOutput を含む単一行の JSON エンベロープ。

よくある問題Copy Anchor Link

SessionStart がタイムアウトするCopy Anchor Link

最も一般的なのは、find-python ロケーターが Microsoft Store のシムを検出し、 実際のインタープリタの解決に失敗しているケースです。確認してください。

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

コマンドが有効な JSON エンベロープを出力するのに Claude Code パネルにタイムアウトが表示される場合は、 settings.json でそのイベントの timeout を引き上げてください。コマンドがシェルレベルで失敗する場合は、 本物の CPython 3.10+ をインストールし、それが PATH 上にあるかロケーターで検出可能であることを確認してください。

すべての Write/Edit がブロックされるCopy Anchor Link

PreToolUse が、ハーネスのインストールルート（Claude Code アダプターでは ~/.claude/）の外に書き込まれる内容の中のプラン内部用語をフラグしています。 内容に CM-7 違反がないか確認してください（ src/apothem/rules/persistent-conventions-vigilance.md を参照）。コードベース成果物には ドメイン言語のみを使用します。

settings.json が読み込まれないCopy Anchor Link

Claude Code は ~/.claude/settings.json を読み込みます。Apothem が期待される ハーネスルートにインストールされていることを確認し、ファイル変更後にセッションを再起動してください。

フックが静かに何もしないCopy Anchor Link

フックの契約は「常に 0 で終了し、常に有効な JSON を出力する」です。インタープリタを 特定できない場合、ロケーターは空を返し、コマンドは no-op になります。chaos_pass.py を実行して、 構成済みの各フックが有効なエンベロープを返すことを確認してください — ライブセッションでは隠れてしまう 劣化した解決パスを捕捉します。

レイヤー化された優先順位Copy Anchor Link

Claude Code は、優先順位の昇順で 3 つのレイヤーを合成することで、有効な設定オブジェクトを 解決します。

上位段階の値は リーフキーレベルで 下位段階の値を上書きします — プロジェクト レイヤーとユーザーローカルレイヤーの両方が permissions.allow エントリを宣言する場合は和集合が 取られます。両方が theme のようなスカラーを宣言する場合は、ユーザーローカルの値が勝ちます。正確な キーごとのマージセマンティクスは Claude Code ハーネスが所有します。

ユーザーローカルオーバーライドの作成Copy Anchor Link

1. examples/harnesses/claude-code/settings.local.example.json を <harness-root>/settings.local.json にコピーします。 ファイル名 settings.local.json は .gitignore のパターンに一致するため、このファイルがバージョン管理に入ることは決してありません。
2. ローカルのコピーを編集します。上書きするキーだけを残してください。ハーネスはレイヤーを合成するため、存在しないキーはプロジェクトのレイヤーから継承されます。
3. 保存する前に、ファイルが有効な JSON として解析できることを確認してください。ハーネスは、セッション開始時に不正な形式の JSON を拒否します。