> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle Hooks

> フックイベントと、各段階で利用できるデータについて

各フックイベントは、エージェントのライフサイクル内の特定の時点で発火します。どのツール呼び出しでフックがトリガーされるかを絞り込むには、**matcher** フィールド (フックイベントの `tool_name` に一致する正規表現) を利用します。

***

<div id="pretooluse">
  ## PreToolUse
</div>

ツールが実行される**前**に呼び出されます。これを利用して、ツール呼び出しをブロックしたり、変更したり、前提情報を追加したりできます。

**標準入力データ:**

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

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

```json theme={null}
{
  "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/ 外への書き込みでは確認を必須にする:**

ツールへの入力を検査し、判定を返すスクリプトを利用します。

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

***

<div id="posttooluse">
  ## PostToolUse
</div>

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

**標準入力データ:**

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

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

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

***

<div id="permissionrequest">
  ## PermissionRequest
</div>

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

**標準入力データ:**

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

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

```json theme={null}
{
  "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)\""
        }
      ]
    }
  ]
}
```

***

<div id="userpromptsubmit">
  ## UserPromptSubmit
</div>

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

**標準入力データ:**

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

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

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

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

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Deploys require an approved change ticket."
  }
}
```

***

<div id="stop">
  ## Stop
</div>

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

**標準入力データ:**

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

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

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

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

***

<div id="postcompaction">
  ## PostCompaction
</div>

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

**標準入力データ:**

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

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

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

***

<div id="sessionstart">
  ## SessionStart
</div>

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

**標準入力データ:**

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

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

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

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

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Session started. Project uses ESM imports only."
  }
}
```

***

<div id="sessionend">
  ## SessionEnd
</div>

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

**標準入力データ:**

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

***

<div id="matching-multiple-events">
  ## 複数のイベントへのマッチング
</div>

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

```json theme={null}
{
  "PreToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ]
}
```

<div id="using-the-matcher">
  ## Matcher の利用
</div>

`matcher` フィールドは、フックイベントの `tool_name` に対してマッチする **regex** です。利用できるのは、ツール関連のイベント `PreToolUse`、`PostToolUse`、`PermissionRequest` です。

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

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

| 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` ツール |

<div id="tool-names-you-can-match">
  ### 一致対象にできるツール名
</div>

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

一般的な公開コアツール名は次のとおりです。

* `read`
* `edit`
* `grep`
* `glob`
* `exec`

MCP server のツールは、`mcp__<server>__<tool>` の形式で表示されます。たとえば、`github` という MCP server の `create_issue` という名前のツールは、`mcp__github__create_issue` として表示されます。

その他のツールについては、フックの stdin に表示される `tool_name` に正確に一致させてください。現在のセッションで利用可能な完全な一覧を確認するには、`matcher: ""` を指定した一時的な `PostToolUse` フックを追加し、stdin のペイロードをログに記録してください。