フック機能 - Q CLI

エージェントのライフサイクルやツール実行時にカスタムコマンドを実行する機能です。セキュリティ検証、ログ記録、コンテキスト収集などに使用できます。

フックの種類

AgentSpawn

エージェント起動時に実行。出力は会話コンテキストに追加されます。

UserPromptSubmit

ユーザーがプロンプトを送信した時に実行。出力は会話コンテキストに追加されます。

PreToolUse

ツール実行前に実行。ツールの実行をブロックできます。

PostToolUse

ツール実行後に実行。ツールの結果にアクセスできます。

エージェント設定での定義

基本構造

{
  "description": "フック使用例",
  "hooks": [
    {
      "name": "AgentSpawn",
      "command": "echo",
      "args": ["エージェント起動"]
    }
  ]
}

ツールマッチング

特定のツールに対してのみフックを実行：

{
  "hooks": [
    {
      "name": "PreToolUse",
      "matcher": "fs_write",
      "command": "echo",
      "args": ["ファイル書き込み前チェック"]
    }
  ]
}

マッチャーの例:

"fs_write" - 特定のツール
"fs_*" - ワイルドカード
"@git" - MCPサーバーの全ツール
"@git/status" - MCPの特定ツール
"*" - 全ツール
"@builtin" - 組み込みツールのみ

終了コードの動作

0: 成功。STDOUTはキャプチャされる（AgentSpawn/UserPromptSubmitではコンテキストに追加）
2: (PreToolUseのみ) ツール実行をブロック。STDERRがLLMに返される
その他: 失敗。STDERRが警告として表示される

タイムアウト設定

{
  "hooks": [
    {
      "name": "PreToolUse",
      "command": "long-running-script.sh",
      "timeout_ms": 60000
    }
  ]
}

デフォルト: 30秒（30,000ms）

キャッシュ設定

成功したフック結果をキャッシュ：

{
  "hooks": [
    {
      "name": "AgentSpawn",
      "command": "expensive-operation.sh",
      "cache_ttl_seconds": 3600
    }
  ]
}

0: キャッシュなし（デフォルト）
> 0: 指定秒数キャッシュ
AgentSpawnフックはキャッシュされない

実践例

セキュリティチェック

{
  "hooks": [
    {
      "name": "PreToolUse",
      "matcher": "execute_bash",
      "command": "security-check.sh",
      "args": []
    }
  ]
}

security-check.sh:

#!/bin/bash
event=$(cat)
command=$(echo "$event" | jq -r '.tool_input.command')

if [[ "$command" == *"rm -rf"* ]]; then
  echo "危険なコマンドが検出されました" >&2
  exit 2  # ツール実行をブロック
fi

exit 0

コンテキスト収集

{
  "hooks": [
    {
      "name": "AgentSpawn",
      "command": "git",
      "args": ["status", "--short"]
    }
  ]
}

ログ記録

{
  "hooks": [
    {
      "name": "PostToolUse",
      "matcher": "fs_write",
      "command": "log-file-changes.sh"
    }
  ]
}

MCPツールのフック

{
  "hooks": [
    {
      "name": "PreToolUse",
      "matcher": "@postgres/query",
      "command": "validate-sql.sh"
    }
  ]
}

注意事項

フックはエージェント設定ファイルで定義
PreToolUseのみツール実行をブロック可能（終了コード2）
AgentSpawnフックはキャッシュされない
タイムアウトはデフォルト30秒
フックコマンドは同期実行される