hook から権限リクエストに応答する（PermissionRequest）

01PermissionRequest と PreToolUse、Notification の比較

権限に関わる hook イベントは 3 つあり、それぞれ役割が異なります。

prompt そのものに関心がある場合、つまり応答する、ログに残す、どこかに送るといった用途には PermissionRequest を使います。6 秒の遅延なしにすぐ発火します。「rm -rf は絶対に実行しない」のように、すべての呼び出しに適用すべきルールには PreToolUse を使います。prompt が表示されない場合でも実行されるためです。このイベントのタイミングについてはNotification hook ガイドで説明しています。

02hook が受け取るデータ

PermissionRequest hook は、共通フィールドに加えて、Claude が実行しようとしている呼び出しの tool_name と tool_input、そしてオプションの permission_suggestions 配列を受け取ります。

{
  "session_id": "abc123",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

permission_suggestions には、このリクエストに対して Claude Code が提案するルール変更が入ります。ダイアログごとに独自の選択肢を組み立てるため、ダイアログの選択肢と完全に一致するわけではありません。

03decision オブジェクト

hookSpecificOutput 内で decision を返します。

覚えておきたいルールが2つあります。

• deny ルールと ask ルールは引き続き適用されます。hook が "allow" を返しても、設定内の一致する deny ルールは上書きされません。また、変更された入力もこれらのルールで再チェックされます。
• ここでは終了コード 2 は無視されます。多くのイベントでは exit 2 でブロックできますが、PermissionRequest hook が decision オブジェクトなしで 2 で終了しても、プロンプトはそのまま表示されます。拒否したい場合は decision を返してください。

04例: 特定のプロンプトを自動承認する

Anthropic 公式の例では、Claude がプランを作り終えたときに表示される ExitPlanMode のプロンプトを承認し、毎回聞かれないようにしています。

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

matcher はできるだけ絞り込んでください。空の matcher や .* で一律に allow すると、ファイル書き込みやシェルコマンドも含め、すべてのプロンプトが承認されてしまいます。

05例: コマンドの内容を見て判断する

このスクリプト(jq が必要)は、git push に関わるものを Claude が読める理由付きで拒否し、それ以外のプロンプトは何も出力せずにあなたの判断に任せます。

#!/bin/bash
# ~/.claude/hooks/permission-check.sh
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")

case "$cmd" in
  *"git push"*)
    jq -nc '{hookSpecificOutput: {hookEventName: "PermissionRequest",
             decision: {behavior: "deny",
                        message: "Pushing is not allowed from this session. Commit and stop."}}}'
    ;;
esac
exit 0

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-check.sh" }]
      }
    ]
  }
}

JSON は文字列連結ではなく jq で組み立てましょう。そうすればメッセージ内の引用符で壊れることがありません。また、stdout にほかの出力が混ざらないようにしてください。シェルのプロファイルが何か echo していると、Claude Code は decision を読み取れません。

06例: 許可してセッション中は記憶させる

リクエストを承認し、セッションが終わるまで Claude に再度聞かれないようにするには、destination: "session" を指定した updatedPermissions エントリを追加します。hook は受け取った permission_suggestions のひとつを、destination だけ変えてそのまま返せます。

#!/bin/bash
input=$(cat)
jq -c '{hookSpecificOutput: {hookEventName: "PermissionRequest",
        decision: {behavior: "allow",
                   updatedPermissions: [(.permission_suggestions // [])[]
                                        | select(.type == "addRules")
                                        | .destination = "session"]}}}' <<<"$input"

このままでは受け取ったリクエストをすべて許可するので、絞り込んだ matcher と組み合わせてください。destination には localSettings、projectSettings、userSettings も指定でき、その場合はメモリ上ではなく設定ファイルにルールが書き込まれます。

07多くの場合は permission ルールのほうが適している

答えが常に同じなら hook は不要です。settings.json にルールを書けば、Claude Code は何も実行せずに適用します。

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "deny": ["Bash(git push *)"]
  }
}

ルールは deny、ask、allow の順に評価されます。hook が役立つのは、時間帯や作業中のブランチ、別の場所にいる人の返答など、ルールでは判断できない要素に応じて決めたい場合です。そのほかの組み込みオプションについては permission モードの解説をご覧ください。

08ハマりやすいポイント

• 非対話実行。claude -p では確認する相手がいません。PermissionRequest hook は実行されますが、どれも decision を返さなければ呼び出しは拒否されます。
• タイムアウト。command hook はデフォルトで最大600秒実行でき、その間 Claude は待機します。人の返答など時間のかかるものを待つ hook では、timeout(秒単位)を設定してください。
• 発火しないプロンプトもあります。サンドボックス内コマンドのネットワークリクエストでは PermissionRequest は実行されません。その場合は permission_prompt 通知タイプを使ってください。
• セキュリティ。"allow" を返す hook は、あなたのユーザー権限で、あなたの代わりに操作を承認していることになります。コマンドを実行できるほかのコードと同様にレビューしてください。

09Claude Code Notifier の位置づけ

PermissionRequest hook を書く一番よくある理由は、キーボードの前にいないときにプロンプトに応答することです。自作する場合、hook がリクエストをどこかに送り、返答を待ち、タイムアウト前に返す必要があります。実現は可能で、チャットボットで作っている人もいます。

Claude Code Notifier ならこれをまとめて引き受けます。無料のコマンドラインツール ccn は Mac、Windows、Linux で動作し、~/.claude/settings.json に hook をインストールします。iPhone または Android アプリとペアリングすると、permission リクエストがスマホに届き、1回だけ許可・セッション中は許可・拒否を選べます。その決定を ccn が PermissionRequest hook から返します。直近30秒以内に入力していれば待機せず、terminal で通常どおり確認されます。離席中は、設定した上限(hold_ceiling_seconds、デフォルト600)までスマホからの返答を待ち、キーボードに触れた時点で待機をやめます。本ツールは独立した製品で、Anthropic によるものではありません。ワークフローはスマホから permission を承認する、セキュリティ面はリモート承認は安全か?をご覧ください。

10よくある質問