Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

parentSettingsBehavior 管理者階層キー（'first-wins' | 'merge'）を追加：管理者が SDK の managedSettings（親階層）をポリシーマージに組み込めるようになりました

原文（英語） ​

Added parentSettingsBehavior admin-tier key ('first-wins' | 'merge') to let admins opt SDK managedSettings (parent tier) into the policy merge

概要 ​

parentSettingsBehavior は、Claude Code の管理者設定において、Agent SDK やIDE拡張機能が提供する「親設定（parent settings / managed settings）」を管理者ポリシーとどのようにマージするかを制御するキーです。first-wins（デフォルト）では親設定は無視され管理者設定のみが有効になり、merge では親設定が管理者設定の下位として適用されます。エンタープライズ環境でAgent SDKを使ったカスタム統合を行う際のポリシー管理に重要な設定です。

基本的な使い方 ​

管理者設定（admin-tier managed settings）ファイルに追加します。

json
{
  "parentSettingsBehavior": "merge"
}

デフォルト値は "first-wins" です。

実践例 ​

first-wins モード（デフォルト）：管理者設定を最優先 ​

json
{
  "parentSettingsBehavior": "first-wins",
  "permissions": {
    "allow": ["Bash(npm *)", "Read(*)", "Write(src/*)"]
  }
}

first-wins の動作：

  • SDK の managedSettings や親プロセスが提供する設定は完全に無視される
  • 管理者が設定した内容だけが有効
  • 厳格なセキュリティポリシーを維持したい場合に適している
python
# Agent SDK側でmanagedSettingsを設定しても...
client.claude_code.run(
    prompt="...",
    managed_settings={
        "permissions": {
            "allow": ["Bash(*)", "Write(*)"]  # これは無視される
        }
    }
)

merge モード：SDK設定を管理者設定に統合 ​

json
{
  "parentSettingsBehavior": "merge",
  "permissions": {
    "deny": ["Bash(rm -rf *)", "Write(/etc/*)"]
  }
}

merge の動作：

  • SDK の managedSettings が管理者設定の下位階層として適用される
  • ただし管理者設定は常に優先（ポリシーを「緩くする」ことはできない）
  • SDK側のアプリ固有の設定と組織ポリシーを共存させたい場合に適している
python
# Agent SDKでの設定がmergeされる（ただし管理者設定が優先）
client.claude_code.run(
    prompt="...",
    managed_settings={
        "permissions": {
            "allow": ["Read(src/*)"]  # これが有効になる（管理者設定の deny と矛盾しない範囲で）
        }
    }
)

エンタープライズ統合のシナリオ ​

複数のチームが独自のAgent SDK統合を持ちながら、組織全体のポリシーを維持する場合：

管理者設定（全組織共通）：

json
{
  "parentSettingsBehavior": "merge",
  "permissions": {
    "deny": [
      "Bash(curl * http://*)",
      "Write(/etc/*)",
      "Write(/var/*)"
    ]
  }
}

チームAのSDK設定（開発チーム）：

python
managed_settings={
    "permissions": {
        "allow": ["Bash(npm *)", "Write(src/*)", "Read(*)"]
    }
}

チームBのSDK設定（データチーム）：

python
managed_settings={
    "permissions": {
        "allow": ["Bash(python *)", "Write(notebooks/*)", "Read(data/*)"]
    }
}

管理者の deny ルールは両チームに適用されつつ、各チームの許可ルールも有効になります。

注意点 ​

  • parentSettingsBehavior は 管理者設定（admin-tier）専用 です。ユーザー設定やプロジェクト設定には設定できません
  • merge モードでも、親設定（SDK設定）が管理者設定より緩いポリシー（より多くを許可）を設定しようとしても、管理者設定が優先されます
  • 親設定は管理者設定の「ポリシーを締める」方向には機能できますが、「ポリシーを緩める」方向には機能しません
  • この設定を使うには Agent SDK または IDE 拡張機能との統合が前提となります
  • 設定の階層について不明な場合は、管理者設定を first-wins に保つことで予期しない権限付与を防止できます

関連情報 ​