Agent SDK settingSources — Claude Codeの機能をどこまで制御できるか

何も渡さないと、手元のClaude Code設定がそのまま入る

settingSourcesを省略したquery()は、Claude Code CLIと同じ入力を読みます。ユーザー設定・プロジェクト設定・ローカル設定、CLAUDE.md、.claude/配下のskills・agents・commandsです。["user", "project", "local"]を渡したのと同じ状態で始まります。CLIで動いていた設定がSDKでもそのまま効くのは便利ですが、開発者のホームディレクトリの設定が本番のエージェントに紛れ込む入口にもなります。

止めたいときはsettingSources: []を渡します。プログラムで明示した内容だけがセッションに反映されます。ただし、これで完全に隔離できるわけではありません。何が止まり、何が止まらないかを、症状と目的の側から順に見ていきます。SDKでエージェントを最小構成から組み立てる手順はClaude Agent SDK入門にあります。

3つのソースが読み込むもの

settingSources(Pythonはsetting_sources)は"project" / "user" / "local"の配列です。<cwd>はcwdオプションで渡した作業ディレクトリで、省略時はプロセスのカレントディレクトリです。

探索範囲は入力ごとにずれます。親ディレクトリまで遡るかどうかが、見落としやすい差です。

settings.jsonだけが<cwd>/.claude/に固定されています。モノレポのサブディレクトリをcwdにすると、ルートの.claude/settings.jsonは読まれない一方、ルートのCLAUDE.mdとskillsは読まれます。「CLAUDE.mdは効いているのにpermissionsが効かない」という症状の典型的な原因です。

CLIとSDKで3値が共通

v2.1.287のclaude --helpには、SDKのsettingSourcesと同じ3値を取るフラグがあります。

claude --help | grep -A1 -E "^  --setting-sources"

  --setting-sources <sources>           Comma-separated list of setting sources
                                        to load (user, project, local).

claude --setting-sources user,projectのように起動すれば、localを外した状態を対話セッションで試せます。同じヘルプには--bareと--safe-modeもあり、挙動が違います。--bareは設定の自動探索に加えて認証も絞り、Anthropic認証がANTHROPIC_API_KEYかapiKeyHelperだけになってOAuthとキーチェーンは読まれません。--safe-modeはCLAUDE.md・skills・プラグイン・hooks・MCP・自動メモリーなどのカスタマイズをすべて無効にして起動します。認証・モデル選択・組み込みツール・権限は通常どおり使います。管理者ポリシーの設定(ポリシーで設定したhooksなど)は適用され続けますが、managedのCLAUDE.mdとskills、プラグイン、ポリシー設定のMCPサーバーは読み込まれません。

--setting-sourcesは読み込む設定源を選ぶだけのフラグです。指定したリストは、agent viewでバックグラウンドに回したセッションやagent teamsのメンバーにも引き継がれます。--add-dirで追加したディレクトリでも、localを外せばそこのCLAUDE.local.mdは読み込まれません。

CLAUDE.mdは衝突し、settings.jsonは上書きされる

CLAUDE.mdは"project" / "local" / "user"のどれを含むかで、置き場所と読み込みタイミングが変わります。

• プロジェクトルートとcwdより上の親ディレクトリのCLAUDE.md: "project"を含めばセッション開始時
• cwdより下のサブディレクトリのCLAUDE.md: エージェントがそのサブツリーのファイルを読んだとき
• CLAUDE.local.md: "local"を含むときだけ
• ~/.claude/CLAUDE.mdと~/.claude/rules/*.md: "user"を含むときだけ

衝突の扱いは、CLAUDE.mdとsettings.jsonで別物です。

CLAUDE.mdの矛盾を避けるには、書く内容を食い違わせないか、具体的なほうのファイルに「この指示はユーザー側の既定値より優先する」と明記します。CLAUDE.mdの書き方そのものはClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンにまとまっています。

Skillsが見つからないとき

Skillsはファイルシステムから発見され、settingSourcesが"project"か"user"を含むときだけ見つかります。settingSources: []のままskills: "all"を渡しても、発見されるSkillsが0件のため、Skillsは読み込まれません。skillsを省略すると、発見されたユーザー・プロジェクトのSkillsが有効になり、Skillツールも使えます。

Pythonには、省略時の既定値に落とし穴があります。Pythonのリファレンスでは、skillsを指定してsetting_sourcesを省略した場合、読み込まれるのはユーザーとプロジェクトだけで、ローカル設定は含まれません。settings.local.jsonやCLAUDE.local.mdを効かせたいなら、setting_sources=["user", "project", "local"]を明示します。TypeScriptのリファレンスでは、省略時の既定はCLIと同じ3ソースとされています。

options = ClaudeAgentOptions(
    skills="all",
    setting_sources=["user", "project", "local"],  # localも欲しいなら明示する
)

Hooksの2経路は並走する

Hooksには、settings.jsonに書くシェルコマンド形式のfilesystem hooksと、query()に直接渡すプログラム形式のコールバックがあり、両方が並走します。settingSourcesに該当ソースが含まれていれば、filesystem hooksは自動で読み込まれます。すでにプロジェクトの.claude/settings.jsonにhooksがあり、settingSources: ["project"]を渡しているなら、追加の設定なしでSDKセッションでも動きます。

filesystem hooksが扱える形式は次の5つです。メインエージェントと、そこから派生したsubagentsの両方で発火します。

プログラム形式のコールバックもsubagent内で発火し、入力にagent_idとagent_typeが入るので、どのエージェントの呼び出しか区別できます。TypeScript SDKだけがSessionStart・SessionEnd・TeammateIdle・TaskCompletedといった追加イベントに対応します。コールバック側の書き方はAgent SDKのHooks解説、settings.json側の設定と実用パターンはClaude Code Hooks完全ガイドにあります。

settingSourcesが制御しない5つの入力

settingSources: []を渡しても読み込まれる入力が5つあります。

自動メモリーはWrite・Editの標準ツールで書き込まれるため、この2つを有効にしている限り新しいメモリーが増えます。claude.aiのMCPコネクタは、claude setup-tokenで発行した長期トークン(CLAUDE_CODE_OAUTH_TOKEN)では読み込まれません。このトークンはモデルへのリクエストにしか使えないためです。strictMcpConfigは、mcpServersで渡したサーバー以外を、プロジェクトの.mcp.json・ユーザー設定・プラグイン由来のMCPサーバーも含めて無視します。一方disableClaudeAiConnectorsが効くのは、Claude Code自身が取得するコネクタだけです。クラウドホストやデスクトップアプリが渡してくるコネクタには効きません。

サンドボックスの行は他の4つと向きが逆です。Claude Codeはこれらのエントリを、サンドボックス内コマンドが触れる範囲を狭める目的でしか使いません。削除すれば緩むので、隔離のために「消す」判断は安全側に倒れません。

隔離したセッションを作る

ホストの設定から切り離したセッションが欲しいとき、操作は次の順になります。

const options = {
  settingSources: [], // ユーザー・プロジェクト・ローカル設定を読み込まない
  strictMcpConfig: true, // claude.aiコネクタ等を持ち込まない
  env: {
    CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1", // 自動メモリーの読み書きを止める
  },
};

これでも、組織のOAuthログインで認証していればserver-managed settingsは取得されます。ファイルシステムを分けても組織側のポリシーは切り離せません。マルチテナントではデフォルトのquery()オプションに頼らないよう公式が警告しており、理由は5つの入力がホスト単位・組織単位で共有されるからです。例えば同じホスト・同じプロジェクトディレクトリを使う2つのテナントがあると、一方が書いた自動メモリーが、他方の起動時にシステムプロンプトへ入る経路ができます。ファイルシステム分離の具体策はAgent SDKのセキュアなデプロイ、セッション・ハーネス・サンドボックスの分け方はManaged Agentsの設計思想でも扱っています。

実際に何が読み込まれるかを事前に見る

TypeScript SDKには、query()を起動せずに設定の解決結果を見るresolveSettings()があります(アルファ版で、APIは変わる可能性があります)。cwdとsettingSourcesを渡すと、次の3つが返ります。

• effective: 有効なソースを優先順位どおりにマージした設定
• provenance: 各トップレベルのキーを、どのソースが供給したか
• sources: ソースごとの生の設定(優先度の低い順)

「settings.jsonを直したのに反映されない」「ユーザー側の値が勝っているのでは」という疑いを、実際に起動する前に確かめられます。ただしライブのセッションとは差があります。管理者設定のpolicyHelperは実行されず、server-managed settingsはserverManagedSettingsを渡さない限り含まれません。プロジェクトやローカルのpermissions.defaultModeにある'auto'や'bypassPermissions'も、ライブセッションでは無視される値がそのまま出ます。

機能ごとに何を使うか

CLAUDE.md・Skills・Subagents・Hooks・MCPは、どれも「Claudeの挙動を拡張する」点で似ていますが、使う面が違います。

有効にした機能はどれもコンテキストウィンドウを消費します。CLAUDE.mdは毎セッション読み込まれ、Skillsは説明文だけが起動時に渡されて、本文は関連するときに読み込まれます。頻繁に参照する短い規約はCLAUDE.mdに、たまにしか使わない長い手順書はSkillsに置くと、同じ情報量でも消費を抑えられます。

ここでsettingSourcesの設計に跳ね返る点があります。CLAUDE.mdとSkillsを両方"project"ソースに頼っていると、絞る操作が両方に同時に効きます。片方だけ止めたいなら、ソースの切り替えでなく、CLAUDE.mdの記述量を減らすかskillsオプションで個別に絞ります。

よくある質問

Agent teamsもsettingSourcesで制御しますか

しません。複数のClaude Codeインスタンスがタスクリストを共有して連携するAgent teamsは、SDKのオプションで直接構成する機能ではありません。1つのセッションがチームリードとして振る舞うCLI側の機能です。

settingSourcesとsystemPromptはどう使い分けますか

CLIとSDKで同じ指示を共有したいなら、CLAUDE.md経由でsettingSourcesから読みます。SDKアプリだけに閉じた指示は、systemPromptでCLAUDE.mdを介さず直接渡せます。書き方はAgent SDKのシステムプロンプト設定にあります。

まとめ

settingSources: []だけでは、隔離で最も漏れやすい自動メモリーとclaude.aiコネクタが残ります。前者はCLAUDE_CODE_DISABLE_AUTO_MEMORY、後者はstrictMcpConfig: trueで別に止めます。