hooks-management

フック管理

自然言語のコマンドでフックと自動化を管理します。

重要：フックを追加、変更、削除した後は、変更を反映するためにエージェントの再起動が必要であることを、必ずユーザーに伝えてください。フックは起動時に読み込まれます。

クイックリファレンス

フックイベント（2026-04 時点の Claude Code：28 イベント）：

• セッションライフサイクル：SessionStart、SessionEnd、InstructionsLoaded
• ユーザー入力：UserPromptSubmit、UserPromptExpansion
• ツール実行：PreToolUse、PostToolUse、PostToolUseFailure、PostToolBatch
• 権限：PermissionRequest、PermissionDenied
• モデル出力：Stop、StopFailure
• サブエージェント／タスク：SubagentStart、SubagentStop、TaskCreated、TaskCompleted、TeammateIdle
• 設定／状態：ConfigChange、FileChanged、CwdChanged
• 圧縮：PreCompact、PostCompact
• ワークツリー：WorktreeCreate、WorktreeRemove
• MCP：Elicitation、ElicitationResult
• 通知：Notification

ハンドラーの種類：command、http、mcp_tool、prompt、agent。一部のイベントはコマンド専用です（PostCompact、PermissionDenied、Elicitation／ElicitationResult、FileChanged、CwdChanged、ConfigChange、InstructionsLoaded、WorktreeCreate／Remove、SubagentStart、StopFailure、TeammateIdle、Setup、SessionStart、SessionEnd、Notification）。

Claude Code の設定ファイル：

• ユーザー全体：~/.claude/settings.json
• プロジェクト：.claude/settings.json
• ローカル（コミット対象外）：.claude/settings.local.json
• 追加ポリシーファイル：~/.claude/managed-settings.d/（managed-settings のみ）

Codex CLI／Codex App の設定ファイル（2026-06 時点）：

• ユーザー設定：~/.codex/config.toml
• ユーザーフック：~/.codex/hooks.json、または ~/.codex/config.toml 内のインライン [hooks] テーブル
• プロジェクトフック：<repo>/.codex/hooks.json、または <repo>/.codex/config.toml 内のインライン [hooks] テーブル（信頼済みのプロジェクトのみ）
• Codex App と CLI はこれらの設定レイヤーを共有します。App／IDE では、設定 UI から同じ config.toml が開きます。
• フックはデフォルトで有効です。無効にするには [features].hooks = false を使用します。codex_hooks は非推奨のエイリアスです。
• 管理対象外の Codex コマンドフックは、/hooks で確認して信頼する必要があります。変更されたフック定義は、信頼されるまでスキップされます。

Devin CLI／デスクトップのフックの場所：

• プロジェクト：.devin/hooks.v1.json（単独のフックオブジェクト。推奨）、または .devin/config.json／.devin/config.local.json 内の "hooks"
• ユーザー：~/.config/devin/config.json 内の "hooks"（Windows では %APPDATA%\devin\config.json）
• read_config_from.claude が有効な場合（デフォルト）、.claude/ 内の Claude 形式のフックは自動的にインポートされます
• イベント：PreToolUse、PostToolUse、PermissionRequest、UserPromptSubmit、Stop、PostCompaction、SessionStart、SessionEnd。matcher は tool_name に対する正規表現です
• イベントと出力の仕様全体については、references/devin-hooks.md を参照してください

Claude Code における PreToolUse のデフォルトの制御方法：標準出力に JSON を出力し、hookSpecificOutput.permissionDecision を "allow"、"deny"、"ask"（組み込みのユーザー確認プロンプトを表示）、または "defer"（ヘッドレスのツール呼び出しを一時停止。-p --resume で再開）に設定します。Decision Control を参照してください。独自の確認方式（環境変数フラグ、対話型の osascript プロンプト、バイパストークン）は実装しないでください。これらは組み込み UX を損ない、既存の permissions.allow エントリーがあると、気付かないまま失敗します。

Codex の例外：Codex の PreToolUse は、まだ "ask" に対応していません。Codex の設定では、確実にブロックする場合は deny／終了コード 2、助言的なコンテキストには additionalContext、ネイティブのプロンプトには Codex の承認ポリシー／権限を使用してください。

すべてのフックを無効にする：settings.json で disableAllHooks: true を設定します。

ワークフロー

1. リクエストを理解する

ユーザーの要望を解析します：

• 追加／作成：特定のイベントとツールに対する新しいフック
• 一覧表示／表示：現在のフック設定を表示
• 削除：特定のフックを削除
• 更新／変更：既存のフックを変更
• 検証：フックにエラーがないか確認

2. 書き込み前に検証する

保存する前に、必ず検証を実行します。

python3 "$SKILL_PATH/scripts/validate_hooks.py" ~/.claude/settings.json

3. 現在の設定を読み取る

cat ~/.claude/settings.json 2>/dev/null || echo '{}'

4. 変更を適用する

変更には Edit ツールを、新しいファイルには Write ツールを使用します。

フックの追加

自然言語をフック設定に変換する

ユーザーの発言	イベント	マッチャー	備考
「すべての bash コマンドを記録して」	PreToolUse	Bash	ファイルに記録
「編集後にファイルをフォーマットして」	PostToolUse	Edit|Write	フォーマッターを実行
「.env ファイルの変更をブロックして」	PreToolUse	Edit|Write	終了コード 2 でブロック
「完了したら通知して」	Notification	""	デスクトップ通知
「コードを変更したらテストを実行して」	PostToolUse	Edit|Write	拡張子で絞り込み
「危険なコマンドの前に確認して」	PreToolUse	Bash	Claude Code：JSON permissionDecision: "ask" を出力します（組み込みの確認 UI）。Codex：可能であれば承認ポリシーを使用します。フックレベルの ask はサポートされていません。
「X には手動承認を必須にして」	PreToolUse	Bash/Edit/Write	Claude Code：JSON permissionDecision: "ask" を出力します。終了コード 2 ではありません。Codex：ポリシーによる確認、または完全なブロックを選択します。
「確認されるまでブロックして」	PreToolUse	Bash	Claude Code：JSON "ask" により、ユーザーは呼び出しごとに許可できます。Codex：フックから確認プロンプトを作成する機能はまだありません。

フック設定テンプレート

{
  "hooks": {
    "EVENT_NAME": [
      {
        "matcher": "TOOL_PATTERN",
        "hooks": [
          {
            "type": "command",
            "command": "SHELL_COMMAND",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

シンプルなフックと複雑なフック

複雑なフックには、スクリプトファイルを優先してください。引用符が入れ子になったインラインコマンド、osascript、複数ステップのロジックは、JSON のエスケープ処理の問題で失敗しやすくなります。

複雑さ	方法	例
シンプル	インライン	jq -r '.tool_input.command' >> log.txt
中程度	インライン	基本的な条件分岐を含む単一の grep/jq パイプ
複雑	スクリプトファイル	ダイアログ、複数の条件、osascript、エラー処理

スクリプトの場所：~/.claude/hooks/（必要に応じて作成）

PreToolUse 用スクリプトテンプレート（~/.claude/hooks/my-hook.sh）— 主な仕組みとして JSON による判定制御を使用します。終了コードは、シンプルなブロックに限りフォールバックとして使用します。

#!/bin/bash
set -euo pipefail

# Read JSON input from stdin
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# Your logic here
if echo "$cmd" | grep -q 'pattern-requiring-confirmation'; then
    # PRIMARY PATTERN for "require user confirmation": emit JSON on stdout.
    # Claude Code will show its built-in confirm prompt to the user.
    jq -n '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "ask",
        permissionDecisionReason: "Explain why this call is risky"
      }
    }'
    exit 0
fi

if echo "$cmd" | grep -q 'pattern-to-hard-block'; then
    # Hard block (no user override possible): JSON deny, NOT exit 2.
    jq -n '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: "Reason shown to Claude"
      }
    }'
    exit 0
fi

exit 0  # Allow (silent)

終了コード 2 や独自のプロンプトではなく、JSON による判定を使う理由：

• permissionDecision: "ask" は、組み込みの Claude Code 確認 UI を呼び出します。ユーザーには明確なプロンプトが表示され、呼び出しごとに許可または拒否できます。
• exit 2 は一律にブロックします。ユーザーは UI から解除できず、Claude は回避策を使って再試行することがよくあります。
• 独自の方式（CONFIRMED=1 のような環境変数フラグ、osascript ダイアログ、バイパストークン）は、ネイティブの操作性を損ない、コマンド履歴に残り、ツールに一致する permissions.allow ルールがすでにある場合は黙って回避されます。

スクリプトを使用するフック設定：

{
  "type": "command",
  "command": "~/.claude/hooks/my-hook.sh"
}

その他のハンドラータイプ（2026）：http（イベント JSON を URL に POST します）、mcp_tool（設定済みの MCP サーバー上のツールを呼び出します）、prompt（LLM でプロンプトを評価し、$ARGUMENTS をサポートします）、agent（ツールを使ってエージェント型の検証を実行します）。一部のイベントはコマンド専用です（PostCompact、PermissionDenied、Elicitation/ElicitationResult、FileChanged、CwdChanged、ConfigChange、InstructionsLoaded、WorktreeCreate/Remove、SubagentStart、StopFailure、TeammateIdle、SessionStart/End、Notification）。

必ず：

1. ~/.claude/hooks/ にスクリプトを作成します
2. 実行可能にします：chmod +x ~/.claude/hooks/my-hook.sh
3. サンプル入力でテストします：echo '{"tool_input":{"command":"test"}}' | ~/.claude/hooks/my-hook.sh

よく使うパターン

ログ記録（PreToolUse）：

{
  "matcher": "Bash",
  "hooks": [{
    "type": "command",
    "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
  }]
}

ファイル保護（PreToolUse、終了コード 2 でブロック）：

{
  "matcher": "Edit|Write",
  "hooks": [{
    "type": "command",
    "command": "jq -r '.tool_input.file_path' | grep -qE '(\\.env|secrets)' && exit 2 || exit 0"
  }]
}

自動フォーマット（PostToolUse）：

{
  "matcher": "Edit|Write",
  "hooks": [{
    "type": "command",
    "command": "file=$(jq -r '.tool_input.file_path'); [[ $file == *.ts ]] && npx prettier --write \"$file\" || true"
  }]
}

デスクトップ通知（Notification）：

{
  "matcher": "",
  "hooks": [{
    "type": "command",
    "command": "osascript -e 'display notification \"Claude needs attention\" with title \"Claude Code\"'"
  }]
}

判定の制御（Claude Code PreToolUse）

Claude Code の PreToolUse フックは、標準出力に JSON を出力してツールの実行を制御します。これはデフォルトの方法です。「黙って許可する／完全にブロックする」よりも細かな制御が必要な場合、特にユーザーに確認を求める場合は、終了コードではなくこの方法を使ってください。

permissionDecision	動作	用途
"allow"	権限チェックを回避し、黙って続行する	安全な呼び出しを事前承認する
"deny"	ブロックし、理由を Claude に表示する	完全なブロック（ユーザーによる上書きなし）
"ask"	Claude Code に組み込まれた確認 UI をユーザーに表示する	「X には手動承認を必須にする」— 標準的なパターン
"defer"	ヘッドレスのツール呼び出しを一時停止し、-p --resume で再開する	ヘッドレス（-p）セッションでの外部システムとの連携

追加の JSON フィールド：

• permissionDecisionReason — "allow"／"ask" の場合はユーザーに、"deny" の場合は Claude に表示されます
• updatedInput — 実行前にツールの入力を変更します
• additionalContext — ツールの実行前に Claude にコンテキストを追加します

危険なコマンドの前にユーザーに確認する（標準的なパターン）

ユーザーが**「手動での確認を必須にする」、「X を実行する前に確認する」、「承認なしに Y を実行しない」**などと言った場合は、このパターンを使います。回避用の環境変数、osascript ダイアログ、確認トークンを独自に作らないでください。組み込みの確認プロンプトは呼び出しごとの許可／拒否に対応しており、既存の permissions.allow ルールと正しく連携する唯一の方法です。

#!/bin/bash
set -euo pipefail
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // empty')

if echo "$cmd" | grep -qE 'supabase\s+db\s+reset'; then
    jq -n '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "ask",
        permissionDecisionReason: "This will destroy and recreate the local database."
      }
    }'
else
    exit 0
fi

理由を付けて拒否する（完全なブロック）

jq -n '{
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "deny",
    permissionDecisionReason: "Destructive command blocked by hook"
  }
}'

注意点："ask" と既存の permissions.allow ルール

ツール呼び出しがすでに .claude/settings.local.json → permissions.allow の項目に一致している場合（たとえば、このセッションで "Bash" が一律に許可されている場合）、フックの "ask" は回避され、呼び出しは黙って続行されます。症状：フックが何もしないように見えます。.claude/settings.local.json を読み、許可ルールの範囲を狭めるか、フックが有効な間は該当するマッチャーに対する一律の許可を削除して原因を特定してください。

出力スキーマの全容については、references/claude-event-schemas.md を参照してください。

Codex CLI / Codex App フック

2026 年 6 月時点では、Codex フックはデフォルトで有効になっており、同じ ~/.codex と信頼済みプロジェクトの .codex 設定レイヤーを通じて、Codex CLI、Codex IDE 拡張機能、Codex App／デスクトップセッションで共有されています。

現在の Codex ライフサイクルイベント：

• SessionStart
• SubagentStart
• PreToolUse
• PermissionRequest
• PostToolUse
• PreCompact
• PostCompact
• UserPromptSubmit
• SubagentStop
• Stop

新しい設定に古い機能フラグを追加しないでください。フックを無効にする必要がある場合は、次を使用してください：

[features]
hooks = false

最小限の PreToolUse ブロックフック：

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 ~/.codex/hooks/policy.py'
timeout = 30
statusMessage = "Checking Bash command"

同等の ~/.codex/hooks.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 ~/.codex/hooks/policy.py",
            "timeout": 30,
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}

各設定レイヤーでは、hooks.json またはインラインの [hooks] のどちらか一方の形式を使用してください。Codex は両方を読み込み、同じレイヤーに両方が存在する場合は警告を表示します。

ブロックの動作：終了コード 2 でブロックされ（stderr が理由になります）、または JSON {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "..."}} を出力します。

Codex の重要な制限：PreToolUse は現在、permissionDecision: "ask" をサポートしていません。"ask" を返すとフックの実行は失敗し、Codex はツール呼び出しを続行します。フェイルクローズの動作にするには、Claude 形式の ask を Codex の deny に対応付けてください。

Claude Code の ask フックを Codex に適応させる場合は、次の順序を優先してください：

1. 確認なしでコマンドを実行してはならない場合は、ハードな deny／終了コード 2 を使用します。
2. リスクのあるアクションをコマンド argv のプレフィックスとして表現でき、ユーザーがベストエフォートの Codex ネイティブプロンプトを明示的に受け入れる場合は、プロンプトには Codex のルールを使用し、その特定の理由コードではフックを無効にします。
3. ログ記録のみを意図している場合を除き、フック全体をシャドーモードにしないでください。そうすると、フックが通常なら検出するすべてのリスクのあるアクションが許可されます。

特に bash-guard では、Codex のライブモードは内部の ask 判定をデフォルトでハードな deny にします。BASH_GUARD_CODEX_DEFER_REASON_CODES に列挙された理由コードのみ、execpolicy に渡すことができます。また、インストーラーがこの環境変数を追加するのは、ユーザーが --codex-native-prompts を指定した場合に限られます。保留する各理由コードには、対応する prefix_rule(... decision="prompt") が必要です。そうでなければ、リスクのあるコマンドが警告なしに許可されてしまいます。

PermissionRequest が発生するのは、Codex がすでに承認を求めようとしている場合のみです。allow、deny、または判定なしを返せますが、通常なら確認なしで実行されるコマンドに対してプロンプトを表示させることはできません。

Codex の PreToolUse は Bash、apply_patch によるファイル編集、MCP ツール呼び出しをインターセプトできますが、完全な強制境界ではありません。より複雑なシェルの実行経路に対するインターセプトは不完全であり、WebSearch／非シェル／非 MCP ツール呼び出しは対象外です。

Codex フックの完全なリファレンス、すべてのイベントの入出力スキーマ、一般的なパターン、従来の AfterAgent／AfterToolUse イベントからの移行については、references/codex-hooks.md を参照してください。

OpenCode フック（プラグインベース）

OpenCode（anomalyco/opencode v1.14.x）は設定ベースのシェルフックを使用しません。フックは、ライフサイクルイベントを購読する TypeScript／JavaScript のプラグインです。PreToolUse に最も近いものは tool.execute.before で、ここで例外をスローするとツール呼び出しがブロックされます。

// .opencode/plugins/env-protection.ts
import type { Plugin } from "@opencode-ai/plugin"

export default (async () => ({
  tool: {
    execute: {
      before: async (input, output) => {
        if (output.args.filePath?.includes(".env")) {
          throw new Error("Reading .env is forbidden")
        }
      },
    },
  },
})) satisfies Plugin

プラグインの配置場所：

• プロジェクト：.opencode/plugins/*.ts
• グローバル：~/.config/opencode/plugins/*.ts
• npm パッケージ：opencode.json の plugin: [] に記載

一般的なイベント：tool.execute.before、tool.execute.after、session.idle、session.created、file.edited、permission.asked、command.executed（合計約 25 件）。

重要な注意事項（v1.14.x）：tool.execute.* フックは MCP ツール呼び出しでは発生しません。MCP ツールへのアクセスを制御するには、代わりに opencode.json の permission ブロックを使用してください。

「確認してから実行」の動作には、プラグイン内での例外スローよりも permission ルールを優先してください。組み込みの確認 UI と連携します：

{ "permission": { "bash": { "rm -rf *": "ask" } } }

イベントの完全な一覧、Claude Code フックからの移行パターン、npm プラグインの配布については、references/opencode-hooks.md を参照してください。

イベント入力スキーマ

各イベントタイプ（Claude Code）の完全な JSON 入力スキーマについては、references/claude-event-schemas.md を参照してください。

検証

フックを確認するには、検証スクリプトを実行します。

python3 "$SKILL_PATH/scripts/validate_hooks.py" <settings-file>

以下を検証します：

• JSON 構文
• 必須フィールド（type、command/prompt）
• 有効なイベント名
• マッチャーパターン（正規表現の妥当性）
• コマンド構文の基本事項

フックの削除

1. 現在の設定を読み取ります
2. イベント、マッチャー、コマンドパターンでフックを特定します
3. hooks 配列から削除します
4. 配列が空の場合は、マッチャーエントリーを削除します
5. イベントが空の場合は、イベントキーを削除します
6. 検証して保存します

終了コード

コード	意味	用途
0	成功／許可	実行を続行します
2	ブロック	シンプルなブロック（PreToolUse では JSON による判断制御を推奨）
その他	エラー	stderr に記録され、詳細モードで表示されます

セキュリティチェックリスト

フックを追加する前に、以下を確認してください。

• 認証情報をログに記録しない
• 機密データを漏えいさせない
• 具体的なマッチャーを使用する（可能な限り * を避ける）
• 入力の解析を検証する
• 長時間の処理に適切なタイムアウトを設定する

トラブルシューティング

フックが起動しない：マッチャーの大文字と小文字の区別を確認し、イベント名が正確であることを確認してください。

コマンドが失敗する：サンプルの JSON 入力を使って、コマンドを単独でテストしてください。

権限が拒否される：スクリプトが実行可能であることを確認してください（chmod +x）。

タイムアウト：timeout フィールドを増やすか、コマンドを最適化してください。