Lifecycle Hooks

各フックイベントは、エージェントのライフサイクル内の特定の時点で発生します。どのツール呼び出しでフックがトリガーされるかを絞り込むには、matcher フィールド (フックイベントの tool_name に一致する正規表現) を利用します。以下のイベント固有フィールドに加えて、すべての stdin ペイロードには、セッションごとに固定の session_id と、ターンごとの prompt_id が含まれます (prompt_id は各ユーザープロンプトごとに更新され、最初のユーザープロンプトより前に発生するイベント (例: SessionStart) には含まれません) — Command Hooks を参照してください。

PreToolUse

ツールが実行される前に発生します。これを利用して、ツール呼び出しをブロックしたり、変更したり、前提情報を追加したりできます。 標準入力データ:

フィールド	説明	例
`tool_name`	呼び出すツールの名前	`exec`, `edit`, `mcp__github__create_issue`
`tool_input`	ツールに渡す引数	`{ "command": "rm -rf /", "shell_id": "main" }`

例 — 破壊的なコマンドをブロックする:

{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "python3 -c \"import sys, json; data = json.load(sys.stdin); cmd = data.get('tool_input', {}).get('command', ''); sys.exit(2 if 'rm -rf' in cmd else 0)\""
        }
      ]
    }
  ]
}

例 — src/ 外への書き込みでは確認を必須にする: ツールへの入力を検査し、判定を返すスクリプトを利用します。

{
  "PreToolUse": [
    {
      "matcher": "edit",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/check-edit-path.sh",
          "timeout": 5
        }
      ]
    }
  ]
}

例 — 実行前にコマンドを書き換える: フックは、標準出力に hookSpecificOutput.updatedInput を出力することで、ツールへの入力を透過的に書き換えることができます (出力形式を参照) 。たとえば、シェルコマンドをラッパー経由で実行するフックスクリプトは次のとおりです。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "rtk git status"
    }
  }
}

書き換えられた引数は、ツール呼び出しが実行される前に反映されるため、エージェントは元のコマンドではなく更新後のコマンドを実行します。

PostToolUse

ツールの実行完了後に実行されます。ログの記録、検証、または後続アクションのトリガーに利用します。 標準入力データ:

Field	Description
`tool_name`	実行されたツールの名前
`tool_input`	渡された引数
`tool_response`	`success` (boolean) 、`output` (string) 、`error` (string または null) を含むオブジェクト

例 — すべてのシェルコマンドをログに記録する:

{
  "PostToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "sh -c 'cat >> ~/.devin-command-log'"
        }
      ]
    }
  ]
}

PermissionRequest

エージェントが許可するかどうかの判断を必要とするときに発生します。これを利用して、カスタムの承認ロジックを実装できます。 標準入力データ:

Field	Description
`tool_name`	許可を要求しているツール
`tool_input`	ツール呼び出しの引数

例 — git コマンドを自動承認する:

{
  "PermissionRequest": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "python3 -c \"import sys, json; data = json.load(sys.stdin); cmd = data.get('tool_input', {}).get('command', ''); print(json.dumps({'decision': 'approve'})) if cmd.startswith('git ') else sys.exit(0)\""
        }
      ]
    }
  ]
}

UserPromptSubmit

ユーザーがメッセージを送信したときに発生します。これを利用して、前提情報を追加したり、ワークフローをトリガーしたりできます。 標準入力データ:

Field	Description
`prompt`	ユーザーのメッセージ本文

例 — すべてのプロンプトに前提情報を挿入する:

{
  "UserPromptSubmit": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"UserPromptSubmit\", \"additionalContext\": \"Deploys require an approved change ticket.\"}}'"
        }
      ]
    }
  ]
}

このコマンドは、イベント名付きの hookSpecificOutput オブジェクト内に additionalContext を標準出力へ出力します。そのテキストはエージェントの前提情報に取り込まれます:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Deploys require an approved change ticket."
  }
}

Stop

エージェントが停止する (ターンを終了する) と発生します。追加の指示を与えたり、早すぎる停止を防いだりするために利用します。 標準入力データ:

フィールド	説明
`stop_hook_active`	stop フックがすでにアクティブかどうか

例 — エージェントにテストを実行するよう促す:

{
  "Stop": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "echo '{\"decision\": \"block\", \"reason\": \"Please run the test suite before stopping.\"}'"
        }
      ]
    }
  ]
}

条件が最終的に満たされないと、処理をブロックする stop フックによってエージェントがループする可能性があるため、注意してください。

PostCompaction

前提情報の圧縮が正常に完了した後に発火します。ログの記録、後続アクションのトリガー、または圧縮中に失われた可能性のある前提情報の再注入に利用します。 標準入力データ:

Field	Description
`summary`	compactor が生成した要約テキスト (要約が生成されなかった場合は null になることがあります)

例 — 圧縮イベントをログに記録する:

{
  "PostCompaction": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "sh -c 'cat >> ~/.devin-compaction-log'"
        }
      ]
    }
  ]
}

SessionStart

新しいセッションが開始されると発生します。初期化、ログ記録、または開発環境のセットアップに利用します。 標準入力データ:

フィールド	説明
`source`	セッションがどのように開始されたか

例 — セットアップスクリプトを実行:

{
  "SessionStart": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/dev-setup.sh",
          "timeout": 10
        }
      ]
    }
  ]
}

SessionStart コマンドでは、標準出力の hookSpecificOutput オブジェクト内に additionalContext を出力して、前提情報を渡すこともできます。

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Session started. Project uses ESM imports only."
  }
}

SessionEnd

セッションが終了したときに発生します。クリーンアップや最終ログの記録に利用します。 標準入力データ:

フィールド	説明
`reason`	セッションが終了した理由

複数のイベントへのマッチング

1 つのhooksファイルで、複数のイベント用のフックを定義できます。

{
  "PreToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ]
}

Matcher の利用

matcher フィールドは、フックイベントの tool_name に対してマッチする regex です。利用できるのは、ツール関連のイベント PreToolUse、PostToolUse、PermissionRequest です。ツール関連以外のイベント (UserPromptSubmit、Stop、PostCompaction、SessionStart、SessionEnd) には tool_name がないため、その種類のすべてのイベントでフックを実行するには、"" を利用するか、matcher を省略します。

matcher は permission glob ではありません。mcp__github__* のようなパターンは permissions では有用ですが、フックの matcher は regex です。フックの matcher では mcp__github__.* を利用してください。

Matcher	一致するもの
`""` (空) または省略	ツールイベントのすべてのツール名
`"exec"`	`exec` を含むツール名
`"^exec$"`	`exec` ツールのみ
`"^(exec\|edit)$"`	`exec` または `edit` のみ
`"^mcp__.*"`	すべての MCP ツール
`"^mcp__github__.*"`	`github` MCP server のすべてのツール
`"^mcp__github__create_issue$"`	`github` MCP server の `create_issue` ツール

一致対象にできるツール名

フックのマッチャーは、フックスクリプトが stdin の tool_name として受け取るものと同じ、外部から見えるツール名に対して評価されます。利用可能な正確なツール名は、CLI モード、モデル、有効になっている統合によって異なる場合があります。カテゴリ別のコアツール名は次のとおりです。

カテゴリ	ツール名
ファイル操作	`read`, `write`, `edit`, `apply_patch`, `notebook_read`, `notebook_edit`
検索	`grep`, `glob`
Shell	`exec`, `get_output`, `write_to_process`, `kill_shell`
Web	`webfetch`
計画とタスク	`todo_write`, `exit_plan_mode`
スキル	`skill`
サブエージェント	`run_subagent`, `read_subagent`
権限	`request_scope`
MCP 管理	`mcp_list_servers`, `mcp_list_tools`, `mcp_call_tool`, `mcp_read_resource`

MCP server のツールは、mcp__<server>__<tool> の形式で表示されます。たとえば、github という MCP server の create_issue という名前のツールは、mcp__github__create_issue として表示されます。その他のツールについては、フックの stdin に表示される tool_name に正確に一致させてください。現在のセッションで利用可能な完全な一覧を確認するには、matcher: "" を指定した一時的な PostToolUse フックを追加し、stdin のペイロードをログに記録してください。

導入ガイド

Editorとの統合

拡張性

Enterprise

リファレンス

変更ログ

PreToolUse

PostToolUse

PermissionRequest

UserPromptSubmit

Stop

PostCompaction

SessionStart

SessionEnd

複数のイベントへのマッチング

Matcher の利用

一致対象にできるツール名

​PreToolUse

​PostToolUse

​PermissionRequest

​UserPromptSubmit

​Stop

​PostCompaction

​SessionStart

​SessionEnd

​複数のイベントへのマッチング

​Matcher の利用

​一致対象にできるツール名

PreToolUse

PostToolUse

PermissionRequest

UserPromptSubmit

Stop

PostCompaction

SessionStart

SessionEnd

複数のイベントへのマッチング

Matcher の利用

一致対象にできるツール名