> ## 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.

# フック

> セッション中に特定のイベントが発生した際にカスタムロジックを実行します

フックを使用すると、エージェントのライフサイクル内のイベントに応じてカスタムロジックを実行できます。フックは、ポリシーの適用、前提情報の追加、アクションの記録、権限の変更、外部システムとの連携に利用できます。

フックは JSON 形式で設定します。これらをプロジェクトの `.devin/` ディレクトリ (またはユーザーレベルの設定) に配置すると、Devin CLI はマッチングするライフサイクルイベントで実行します。`.claude/` ディレクトリ内の既存のフックも自動的に検出されます。詳しくは [Where Hooks Live](#where-hooks-live) を参照してください。

***

<div id="what-can-hooks-do">
  ## Hooksでできること
</div>

<CardGroup cols={2}>
  <Card title="ポリシーを強制" icon="shield">
    危険なコマンドをブロックしたり、特定のアクションで確認を必須にしたり、ファイルへのアクセスを制限したりできます。
  </Card>

  <Card title="前提情報を追加" icon="message">
    特定のツールが呼び出されたときに、追加の指示や情報を渡します。
  </Card>

  <Card title="付随処理を実行" icon="bolt">
    イベント発生時に、スクリプトを実行したり、通知を送信したり、イベントを記録したりできます。
  </Card>

  <Card title="権限を変更" icon="lock">
    状況に応じて、権限を動的に付与または制限できます。
  </Card>
</CardGroup>

***

<div id="quick-example">
  ## 簡単な例
</div>

プロジェクト内に `.devin/hooks.v1.json` を作成します:

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

シェルコマンドを実行する前に、毎回 `./scripts/check-command.sh` が実行されます。このスクリプトは stdin でイベントデータを受け取り、ゼロ以外の終了コードを返すことでそのアクションをブロックできます。

***

<div id="hook-events">
  ## Hook Events
</div>

フックは、以下のライフサイクルイベントに応答できます。

| Event               | 発生するタイミング         |
| ------------------- | ----------------- |
| `PreToolUse`        | ツールの実行前           |
| `PostToolUse`       | ツールの実行完了後         |
| `PermissionRequest` | 権限の判断が必要なとき       |
| `UserPromptSubmit`  | ユーザーがメッセージを送信したとき |
| `Stop`              | エージェントが停止しようとするとき |
| `SessionStart`      | セッションの開始時         |
| `SessionEnd`        | セッションの終了時         |

各イベントと利用可能なデータの詳細については、[ライフサイクルフック](/ja/cli/extensibility/hooks/lifecycle-hooks)を参照してください。

***

<div id="hook-format">
  ## フックの形式
</div>

各フックには、**type** (`command` または `prompt`) 、任意の **matcher** (フックイベントの `tool_name` に対する正規表現) 、および各種設定があります。

```json theme={null}
{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/validate.sh",
          "timeout": 10
        }
      ]
    }
  ]
}
```

| フィールド     | 説明                                                                           |
| --------- | ---------------------------------------------------------------------------- |
| `matcher` | フックイベントの `tool_name` に対してマッチする正規表現。空文字列、または matcher を省略した場合は、すべてのツール名に一致します。 |
| `type`    | シェルコマンドを実行する場合は `"command"`、LLM プロンプトを評価する場合は `"prompt"`。                    |
| `command` | 実行するシェルコマンド (`command` タイプの場合) 。                                             |
| `prompt`  | 評価する LLM プロンプト (`prompt` タイプの場合) 。                                           |
| `timeout` | タイムアウト時間 (秒)  (任意) 。                                                         |

<div id="command-hooks">
  ### コマンドフック
</div>

コマンドフックでは、シェルコマンドを実行します。イベントデータは **stdin** 経由で JSON として渡され、コマンドは **stdout** に JSON を返すことで結果を制御できます (以下の[出力形式](#output-format)を参照) 。

**入力** (stdin) :

```json theme={null}
{
  "hook_event_name": "PreToolUse",
  "tool_name": "exec",
  "tool_input": {
    "command": "rm -rf /"
  }
}
```

`DEVIN_PROJECT_DIR` 環境変数は、プロジェクトのルートディレクトリに自動的に設定されます。

一致対象にできる組み込みツール名と MCP ツール名の形式については、[Matcher の使用](/ja/cli/extensibility/hooks/lifecycle-hooks#using-the-matcher) を参照してください。

<div id="output-format">
  ### 出力形式
</div>

コマンドフックは、結果を制御するために **stdout** に JSON オブジェクトを出力できます。

アクションを承認またはブロックするには、トップレベルの `decision` (必要に応じて `reason` も) を返します。

```json theme={null}
{
  "decision": "block",
  "reason": "Destructive command blocked by policy"
}
```

エージェントの前提情報にテキストを追加するには、イベント名を付けた `hookSpecificOutput` オブジェクト内で `additionalContext` を返します:

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

| 出力フィールド                                | 説明                                                                        |
| -------------------------------------- | ------------------------------------------------------------------------- |
| `decision`                             | アクションを許可する場合は `"approve"`、拒否する場合は `"block"`                               |
| `reason`                               | エージェントに表示される理由                                                            |
| `hookSpecificOutput.hookEventName`     | この出力が適用されるイベント (例: `UserPromptSubmit`、`SessionStart`、`PostToolUse`)       |
| `hookSpecificOutput.additionalContext` | エージェントの前提情報に追加されるテキスト (`UserPromptSubmit`、`SessionStart`、`PostToolUse` 用) |

<div id="exit-codes">
  ### 終了コード
</div>

| コード | 意味                       |
| --- | ------------------------ |
| 0   | 成功 — フックは通常どおり続行         |
| 2   | ブロック — アクションは拒否される       |
| その他 | エラー — ログに記録されるが、ブロックはしない |

***

<div id="where-hooks-live">
  ## フックの格納場所
</div>

Devin CLI は、以下の場所にあるフックを読み取ります。いずれも同じ JSON 形式です。

<div id="project-level">
  ### プロジェクトレベル
</div>

| 場所                            | 説明                                   |
| ----------------------------- | ------------------------------------ |
| `.devin/hooks.v1.json`        | 独立した hooks ファイル (推奨)                 |
| `.devin/config.json`          | 設定ファイル内の `"hooks"` キー                |
| `.devin/config.local.json`    | `"hooks"` キー (ローカルで上書き、gitignore 対象) |
| `.claude/settings.json`       | `"hooks"` キー (Claude Code 形式)        |
| `.claude/settings.local.json` | `"hooks"` キー (Claude Code 形式)        |

<div id="user-level-global">
  ### ユーザーレベル (グローバル)
</div>

| 場所                                                                      | 説明                            |
| ----------------------------------------------------------------------- | ----------------------------- |
| `~/.config/devin/config.json` (`%APPDATA%\devin\config.json` は Windows) | ユーザー設定の `"hooks"` キー          |
| `~/.claude.json`                                                        | `"hooks"` キー (Claude Code 形式) |
| `~/.claude/settings.json`                                               | `"hooks"` キー (Claude Code 形式) |
| `~/.claude/settings.local.json`                                         | `"hooks"` キー (Claude Code 形式) |

<Note>
  `.devin/hooks.v1.json` では、hooks オブジェクトが**ファイル全体**にあたります (ラッパーキーは不要です) 。それ以外の場所では、hooks は設定ファイル内の `"hooks"` キーの下にネストされます。
</Note>

<Note>
  `.claude/` 配下のパスにある hooks は、`read_config_from.claude` が有効な場合 (デフォルト) に読み込まれます。必要に応じて、[ユーザー設定](/ja/cli/reference/configuration/read-config-from)でこれを無効にできます。
</Note>

***

<div id="verifying-hooks">
  ## フックの確認
</div>

現在読み込まれているすべてのフックとそのソースファイルを確認するには、`/hooks` スラッシュコマンドを利用します:

```
/hooks
```

***

<div id="next-steps">
  ## 次のステップ
</div>

<CardGroup cols={2}>
  <Card title="ライフサイクルフック" icon="rotate" href="/ja/cli/extensibility/hooks/lifecycle-hooks">
    各イベントタイプと利用可能なデータについて詳しく解説します。
  </Card>

  <Card title="設定" icon="gear" href="/ja/cli/reference/configuration/read-config-from">
    Devin CLI がフックの読み込み元とする設定場所を制御します。
  </Card>
</CardGroup>