2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Code サブエージェントの権限問題

2
Posted at

はじめに

Claude Code にはサブエージェント(Agent ツール)という機能がある。親セッションが子エージェントにタスクを委託し、それぞれが独立したコンテキストウィンドウで動作する仕組みだ。コードレビュー専用エージェント、テスト実行エージェントなど、役割ごとに分離して並列処理できる。

しかし、2026年4月現在、このサブエージェントの権限継承に深刻な問題がある。親セッションで許可した操作がサブエージェントでは拒否される。bypassPermissions を指定しても、settings.json の allow リストを設定しても、--dangerously-skip-permissions フラグを渡しても、サブエージェントには伝播しない。

この問題は 2025年5月から報告が続いており、2026年4月現在も未修正のままだ。本記事では権限モデルの仕組み、問題の実態、関連Issueの経緯、そして現時点で機能するワークアラウンドを整理する。

対象読者: Claude Code でマルチエージェント構成を組んでいる、または検討しているエンジニア。

環境

  • macOS Tahoe 26.3.1 (Apple Silicon M4)
  • Claude Code v2.1.37
  • モデル: claude-opus-4-6 (1M context)
  • ~/.claude/settings.json にカスタム権限設定あり

Claude Code の権限モデル

権限モードの種類

Claude Code には以下の権限モードがある。

  • default: ツール使用時に毎回確認プロンプトを表示
  • acceptEdits: ファイル編集を自動承認(保護ディレクトリを除く)
  • auto: バックグラウンド分類器がリクエストとの整合性を検証して自動承認(リサーチプレビュー)
  • plan: 読み取り専用。ファイル変更・コマンド実行不可
  • dontAsk: 事前許可されたツール以外を自動拒否
  • bypassPermissions: 権限プロンプトをスキップ(保護ディレクトリを除く)

サブエージェントの権限決定ルール

公式ドキュメントには以下の記述がある。

If the parent uses bypassPermissions, this takes precedence and cannot be overridden.

つまり、サブエージェントの実効権限は次の式で決まる。

effective_permissions = min(child_requested_mode, parent_session_ceiling)

子が bypassPermissions を要求しても、親のモードが auto なら auto が上限になる。親が bypassPermissions なら子もそれを継承する。親のモードがサブエージェントの権限の天井になる。

なぜ min(child, parent) なのか
セキュリティ上、子プロセスが親より高い権限を持つことは許されない ── これ自体は正しい設計判断である。問題は、settings.json の allow リストや --dangerously-skip-permissions フラグといった「ユーザーが明示的に許可した設定」までもが継承されない点にある。

保護ディレクトリの存在

bypassPermissions モードでも、以下のディレクトリへの書き込みは確認プロンプトが表示される。

  • .git/
  • .claude/(一部例外あり)
  • .vscode/
  • .idea/
  • .husky/

ドキュメント上は .claude/commands/、.claude/agents/、.claude/skills/ への書き込みは例外(プロンプトなし)とされている。しかし実際のコードでは これらのパスが逆に保護対象としてハードコードされている ことが Issue コメントで確認されている(後述)。

問題の実態

再現手順と結果

以下の組み合わせを検証した。

検証1: 親 auto + 子 bypassPermissions

# 親セッションを auto モードで起動
claude  # デフォルトまたは設定で auto モード
# サブエージェント起動時に bypassPermissions を指定
Agent({
  mode: "bypassPermissions",
  prompt: "src/index.ts を読んで先頭にコメントを追加して"
})

結果: サブエージェントの Edit/Write が拒否される。auto モードが天井となり、bypassPermissions は無視される。

検証2: 親 auto + 子 auto

Agent({
  mode: "auto",
  prompt: "src/index.ts を編集して"
})

結果: Edit/Write が拒否される。親セッションの auto モード分類器がサブエージェントのツールコールも評価するが、サブエージェント経由の操作は通常より厳しく判定される傾向がある。

検証3: 親 bypassPermissions(--dangerously-skip-permissions)+ 子

claude --dangerously-skip-permissions

結果: サブエージェントも含めて正常に動作する。ただし --dangerously-skip-permissions はサブエージェントに明示的に伝播するのではなく、親の bypassPermissions モードが天井として適用される結果として動作する。

--dangerously-skip-permissions は親プロセスにのみ適用される。 サブエージェント側で同フラグが有効になるわけではない。親の権限モードが bypassPermissions であるため、min(child, bypassPermissions) の結果として子も bypassPermissions 相当になるだけである。

検証4: settings.json の permissions.allow

{
  "permissions": {
    "allow": [
      "Edit",
      "Write",
      "Bash(npm *)",
      "Bash(git commit *)"
    ]
  }
}

結果: サブエージェントに継承されない。親セッションでは許可されるが、サブエージェントでは同じ操作に対して確認プロンプトが表示される。

検証5: --allowedTools CLI フラグ

claude --allowedTools "Edit" --allowedTools "Write"

結果: サブエージェントに継承されない。

検証6: Discord DM パーミッション承認

Claude Code の Discord プラグイン経由でパーミッション承認ダイアログを DM で受け取り、承認する運用。

結果: サブエージェントでは DM パーミッション承認が発火しない。権限の天井で確認ダイアログ以前にブロックされるため、フォールバック手段としても機能しない。

検証結果のまとめ

構成 親の動作 サブエージェントの動作
親 auto + 子 bypassPermissions 正常 Edit/Write 拒否
親 auto + 子 auto 正常 Edit/Write 拒否されやすい
親 bypassPermissions + 子 正常 正常(天井が高い)
settings.json allow 適用される 継承されない
--allowedTools 適用される 継承されない
DM パーミッション承認 機能する 発火しない

関連 GitHub Issues

この問題に関連する Issue は多数あり、最も古いものは 2025年5月まで遡る。

メタ Issue: bypassPermissions の根本的な破綻

#39523 — [META] Bypass permissions mode is fundamentally broken (2026-03-26, OPEN)

12件以上の重複 Issue をまとめたメタ Issue。問題を2つの系統に分類している。

  • 系統1: 保護ディレクトリが bypass モードを無視する(v2.1.78 でのリグレッション)

    • .claude/、.git/ 等への書き込みで、bypassPermissions を含むすべてのバイパス機構が無効化される
    • --dangerously-skip-permissions、settings.json の allow 、PreToolUse フック、いずれも効かない
  • 系統2: 権限モードがセッション中に勝手にダウングレードする

    • bypassPermissions から acceptEdits に無通知で切り替わる
    • 保護ディレクトリへの書き込み確認で「Allow」を選択するとトリガーされる
    • 2025年5月の #1014 から報告されている

ドキュメントとコードの不一致が確認されている。 Issue #39523 のコメントで、Claude Code のバンドルされたソースコード cli.js の解析結果が報告されている。ドキュメントでは .claude/commands、.claude/agents、.claude/skills は保護の例外(プロンプトなし)とされているが、コード上ではこれらのパスが 逆に保護対象として明示的にチェックされている。

サブエージェント固有の権限問題

#40241 — --dangerously-skip-permissions does not propagate to subagents (2026-03-28, OPEN)

--dangerously-skip-permissions で起動した親セッションから Agent ツールでサブエージェントを生成すると、サブエージェントの Edit/Write が毎回確認を要求する。14回の Edit すべてでプロンプトが表示されたとの報告。

#24073 — Teammates spawned in Delegate Mode lose tool access (2026-02-08, CLOSED)

Delegate Mode(Plan モードの一種)で生成されたサブエージェントが、mode: "bypassPermissions" を指定しても Bash、Read、Write、Edit を使用できなくなる。根本原因の仮説として effective_permissions = min(mode_param, lead_session_state) が提示されている。

#37730 — Subagents don't inherit permission settings (2026-03-23, OPEN)

settings.json の permissions.allow に Bash(cat:*) を設定しても、サブエージェントが同コマンドで権限を要求する。worktree セッションではプロジェクトスコープの設定パスが異なるため、さらに問題が悪化する。

#22665 — Subagent does not inherit permission allowlist (2026-02-03, CLOSED as duplicate)

settings.json の allowedTools がサブエージェントに継承されない初期報告。#18950 の重複としてクローズ。

#27661 — Subagents should inherit parent session hooks and permission rules (2026-02-22, CLOSED as duplicate)

フック・権限ルール・CLAUDE.md・プロジェクトメモリがサブエージェントに継承されない。#21460、#18950 の重複としてクローズ。

タイムライン

日付 Issue 内容
2025-05-08 #1014 bypass モード破損の初報告 (v0.2.104)
2025-07-03 #2933 VSCode 拡張が bypass を無視 (v1.0.40)。9ヶ月以上 OPEN
2026-02-03 #22665 サブエージェントが allowlist を継承しない
2026-02-08 #24073 Delegate Mode でサブエージェントがツールを喪失
2026-02-22 #27661 フック・権限の継承を要望
2026-03-18 #35646 v2.1.78 で保護ディレクトリのリグレッション導入
2026-03-20 — Anthropic 社員が「Fix incoming」とコメント → Issue クローズ
2026-03-21 #36887 修正が機能しないとの報告 (v2.1.81)
2026-03-23 #37730 サブエージェントが settings.json を継承しない
2026-03-26 #39523 メタ Issue 作成。v2.1.84 でも未修正
2026-03-28 #40241 --dangerously-skip-permissions が伝播しない
2026-04-07 — #39523 に新コメント。依然として未修正

影響を受けるユースケース

この問題により、以下の構成が実質的に不可能または大幅に制限される。

  • マルチエージェント開発パイプライン: コードレビュー → テスト実行 → コミットの自動化
  • 夜間バッチ処理: 無人環境で複数エージェントが協調してタスクを処理
  • スキル自動生成: .claude/skills/ への動的な書き込みを含むワークフロー
  • CI/CD 統合: サブエージェントによる並列テスト実行
  • Discord/Slack ボット経由の操作: パーミッション承認の UI がサブエージェントで発火しない

Max プラン($200/月)のユーザーからも不満の声が上がっている。 Issue #39523 のコメントでは、Opus エージェントが権限プロンプトで停止し、人間のクリックを待つ状態になることへの強い批判がある。自動化プラットフォームとしての Claude Code の信頼性に関わる問題である。

検証したワークアラウンドと結果

効かなかったもの

ワークアラウンド 結果
サブエージェントに mode: "bypassPermissions" を指定 親が auto の場合、無視される
settings.json の permissions.allow サブエージェントに継承されない
--allowedTools CLI フラグ サブエージェントに継承されない
additionalDirectories で ~/.claude/skills を追加 権限問題には効果なし
Edit(.claude/**) を allow リストに追加 保護ディレクトリのハードコードされたチェックに阻まれる

効いたもの

1. 親セッションを --dangerously-skip-permissions で起動する

claude --dangerously-skip-permissions

親のモードが bypassPermissions になるため、min(child, bypassPermissions) でサブエージェントも最大権限を得る。

このフラグはすべてのセーフティチェックを無効化する。 隔離された環境(コンテナ、VM)でのみ使用すべきである。本番環境やホストマシン上での使用は推奨しない。

2. PreToolUse フックによる権限バイパス

Issue #39523 および #40241 のコメントで紹介されているワークアラウンド。フックは settings.json から読み込まれるため、サブエージェントにも適用される。

#!/bin/bash
# ~/.claude/hooks/auto-approve.sh
# すべてのツールコールを自動承認する
echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"Hook-based permission bypass"}}'
exit 0

~/.claude/settings.json に登録する。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/auto-approve.sh"
          }
        ]
      }
    ]
  }
}

なぜフックは継承されるのか
フックは settings.json ファイルから読み込まれる仕組みであり、サブエージェントも同じファイルを参照する。権限モードやallow リストが「セッション状態」として管理されるのに対し、フックは「設定ファイルの読み込み」として処理されるため、この違いが生じている。ただし、Issue #27661 では「フックもサブエージェントに継承されない」との報告もあり、バージョンや設定の組み合わせによって挙動が異なる可能性がある。

より安全なバリエーションとして、特定のツールのみ承認する版も作成できる。

#!/bin/bash
# ~/.claude/hooks/selective-approve.sh
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')

case "$TOOL" in
    Edit|Write|Read|Glob|Grep)
        # ファイル操作系は自動承認
        echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"Selective bypass via hook"}}'
        ;;
    Bash)
        # Bash は危険なコマンドをブロック
        CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
        if echo "$CMD" | grep -qE 'rm\s+-rf\s+[/~]|git\s+push\s+--force|drop\s+database'; then
            echo "BLOCKED: Dangerous command" >&2
            exit 2
        fi
        echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"Selective bypass via hook"}}'
        ;;
esac
exit 0

3. 揮発セッション(外部プロセス委託)

サブエージェント(Agent ツール)を使わず、tmux + claude --dangerously-skip-permissions で別プロセスとして起動する。親子関係ではなく、独立したセッションとして動作するため権限の天井問題を回避できる。

#!/bin/bash
# run-task.sh <slug> <cwd> "<prompt>"
SLUG=$1
CWD=$2
PROMPT=$3

tmux new-session -d -s "task-${SLUG}" \
  "cd ${CWD} && echo '${PROMPT}' | claude --dangerously-skip-permissions -p"

この方式の制限として、親セッションとの間でリアルタイムな情報のやり取りはできない。結果はファイル経由で受け渡す必要がある。

現時点での現実的な対策

上記の検証結果を踏まえ、ユースケース別に推奨構成を整理する。

隔離環境(コンテナ/VM)での自動化:

--dangerously-skip-permissions で親セッションを起動する。最もシンプルで確実。

ホストマシンでの開発:

PreToolUse フックによる選択的バイパスが現実的。ファイル操作は自動承認、Bash は危険コマンドのみブロックという構成でバランスを取れる。

高い安全性が求められる環境:

サブエージェント(Agent ツール)を使わず、読み取り専用の調査のみサブエージェントに委託する。書き込みが必要な作業は親セッションが直接実行するか、揮発セッションに委託する。

運用ルールの例(CLAUDE.md に記載)
## サブエージェント運用制約

- サブエージェントには **ファイル読み書き・コード生成** を委託する
- **破壊的操作**(rm, ファイル削除)や**ネットワーク操作**(curl, API呼び出し)は親が直接実行する
- サブエージェントが権限エラーで止まった場合は、親が代わりに実行する

まとめ

Claude Code のサブエージェント権限問題は、min(child_requested_mode, parent_session_ceiling) という権限モデルに起因する。設計意図としてはセキュリティ上正しいが、settings.json の allow リストや --dangerously-skip-permissions フラグが伝播しないことで、マルチエージェント構成の実用性が大きく損なわれている。

2025年5月の初報告から11ヶ月が経過し、関連 Issue は少なくとも12件以上。Anthropic 社員による「Fix incoming」コメント後もリグレッションが続いており、修正の見通しは不透明である。

現時点での現実的な選択肢は以下の3つに集約される。

  1. 隔離環境 + --dangerously-skip-permissions — 最も確実だが環境の制約がある
  2. PreToolUse フックによる選択的バイパス — ホストマシンでも使えるが、フック継承の挙動にバージョン依存のリスクがある
  3. サブエージェントを読み取り専用に限定 — 安全だが自動化の利点が大幅に減る

マルチエージェント構成を検討する際は、この権限の天井問題を前提として設計する必要がある。公式の修正を待ちつつ、上記のワークアラウンドで凌ぐのが現状の最善策である。

参考リンク

2
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?