メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

Hooks を使うと、QoderWork の実行フローにおける重要なポイントで、コードを変更することなくカスタムロジックを挿入できます。JSON 設定ファイルを編集するだけで、たとえば次のようなことを実現できます。
  • ツール実行前に危険な操作をブロック
  • ファイル書き込みのたびに自動で lint を実行し、コードスタイルを統一
  • Agent のタスク完了時にデスクトップ通知を送り、画面に張り付く必要をなくす
Prompt による指示とは異なり、Hooks は確定的に動作します。イベントが発火すればスクリプトは必ず実行され、モデルの解釈に結果が左右されることはありません。

​
クイックスタート

以下の例では、rm -rf のような危険なコマンドをブロックする方法を紹介します。
1

スクリプトを作成

mkdir -p ~/.qoderwork/hooks
cat > ~/.qoderwork/hooks/block-rm.sh << 'EOF'
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')

if echo "$command" | grep -q 'rm -rf'; then
  echo "危険なコマンドをブロックしました: $command" >&2
  exit 2
fi

exit 0
EOF
chmod +x ~/.qoderwork/hooks/block-rm.sh
2

設定を追加

~/.qoderwork/settings.json に以下を追加します：
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}
3

動作を確認

QoderWork を開き、Agent に rm -rf を含むコマンドを実行させてみてください。Hook が実行をブロックし、エラーメッセージを Agent にフィードバックします。

​
Hooks の設定

​
設定ファイルの場所

QoderWork はユーザーレベルの設定ファイルから Hook 設定を読み込みます：
場所スコープ説明
~/.qoderwork/settings.jsonユーザー（グローバル）個人設定、すべての QoderWork セッションに適用
ホットリロードはまだサポートされていません — Hook 設定を変更した後は QoderWork を再起動してください。

​
設定フォーマット

{
  "hooks": {
    "イベント名": [
      {
        "matcher": "マッチ条件",
        "hooks": [
          {
            "type": "command",
            "command": "実行するコマンド",
            "timeout": 60
          }
        ]
      }
    ]
  }
}
フィールド必須説明
typeはい"command" 固定
commandはい実行するシェルコマンド
timeoutいいえタイムアウト（秒）、デフォルト 60
matcherいいえマッチ条件。省略するとすべてにマッチ
1 つのイベントに複数の matcher グループを定義でき、各グループに複数の Hook コマンドを含めることができます。

​
matcher ルール

matcher は Hook の発火範囲を決定します。何にマッチするかはイベントによって異なります（各イベントの説明を参照）。
パターン意味例
省略または "*"すべてにマッチすべてのツールで Hook が発火
正確な値完全一致"Bash" は Bash ツールのみで発火
| 区切り複数の値にマッチ"Write | Edit" は Write または Edit で発火
正規表現正規表現マッチ"mcp__.*" はすべての MCP ツールにマッチ

​
Hook スクリプトの作成

Hook スクリプトは stdin 経由で JSON 入力を受け取り、exit code と stdout で動作を制御します。このセクションではすべてのイベントに共通の入出力フォーマットを説明します。イベント固有のフィールドについては Hook イベントを参照してください。
QoderWork は現在、Hook スクリプトに環境変数を注入しません。すべてのデータは stdin JSON 経由で渡されます。セッション ID、作業ディレクトリ、ツール情報が必要な場合は、stdin JSON 入力から解析してください。

​
入力

Hook スクリプトは stdin 経由で JSON データを受け取ります。すべてのイベントに以下の共通フィールドが含まれます：
フィールド説明
session_id現在のセッション ID
cwd現在の作業ディレクトリ
hook_event_nameこの Hook をトリガーしたイベント名
各イベントはこれらに加えて固有のフィールドを追加します（各 Hook イベントの説明を参照）。 jq で入力を解析： 
#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')

​
出力

Hook は exit code と stdout で動作を制御します。 exit code が基本動作を決定します：0 は成功、2 はブロック（stderr の内容が会話に注入され、ブロック可能なイベントでのみ有効）、その他の値は非ブロックエラーです。 stdout JSON（exit 0 の場合のみ解析）は一部のイベントに精細な制御を提供します。サポートされるフィールドは各イベントの説明を参照してください。exit code が 0 以外の場合、stdout は無視されます。

​
Hook イベント

​
SessionStart

セッション開始時に発火します。 matcher： セッションソース
matcher 値発火シナリオ
startup新しいセッションの開始
resume既存セッションの再開
compactコンテキスト圧縮完了後
追加入力フィールド： 
{
  "source": "startup",
  "model": "Auto"
}

​
SessionEnd

セッション終了時に発火します。 matcher： 終了理由
matcher 値発火シナリオ
prompt_input_exitユーザーが入力を終了（Ctrl+D 等）
otherその他の理由
追加入力フィールド： 
{
  "reason": "prompt_input_exit"
}

​
UserPromptSubmit

ユーザーが Prompt を送信した後、Agent が処理する前に発火します。 追加入力フィールド： 
{
  "prompt": "ソート関数を書いてください"
}

​
PreToolUse

ツール実行前に発火します。ツール実行をブロックできます。 matcher： ツール名（例：Bash、Write、Edit、Read、Glob、Grep、MCP ツール名は mcp__server__tool 形式） 追加入力フィールド： 
{
  "tool_name": "Bash",
  "tool_input": {"command": "rm -rf /tmp/build"},
  "tool_use_id": "toolu_01ABC123"
}
ツール実行のブロック： exit code 2、stderr の内容がエラーとして Agent に返されます。完全な例はクイックスタートを参照してください。

​
PostToolUse

ツール実行の成功後に発火します。 matcher： ツール名 追加入力フィールド： 
{
  "tool_name": "Write",
  "tool_input": {"file_path": "/path/to/file.ts", "content": "..."},
  "tool_response": "File written successfully",
  "tool_use_id": "toolu_01ABC123"
}

​
PostToolUseFailure

ツール実行の失敗後に発火します。 matcher： ツール名 追加入力フィールド： 
{
  "tool_name": "Bash",
  "tool_input": {"command": "npm test"},
  "tool_use_id": "toolu_01ABC123",
  "error": "Command exited with non-zero status code 1",
  "is_interrupt": false
}

​
Stop

Agent がレスポンスを完了した後に発火します（メイン Agent、保留中のツール呼び出しがない場合）。Agent の停止をブロックして作業を続行させることができます。 Agent の停止をブロック： exit code 2、stderr の内容がメッセージとして会話に注入され、Agent は作業を続行します。

​
SubagentStart / SubagentStop

サブ Agent の起動・完了時に発火します。SubagentStop は Stop と同様、サブ Agent の停止をブロックできます。 matcher： Agent タイプ名 追加入力フィールド： 
{
  "agent_id": "a1b2c3d4",
  "agent_type": "task"
}

​
PreCompact

コンテキスト圧縮前に発火します。 matcher： トリガー方法
matcher 値発火シナリオ
manualユーザーが手動で /compact を実行
autoコンテキストウィンドウが満杯になった時に自動トリガー
追加入力フィールド： 
{
  "trigger": "manual",
  "custom_instructions": "すべてのツール呼び出し結果を保持"
}

​
Notification

通知イベント発火時（権限リクエスト、タスク完了等）。 matcher： 通知タイプ
matcher 値発火シナリオ
permission権限リクエスト通知
resultAgent の結果通知
追加入力フィールド： 
{
  "message": "Agent is requesting permission to run: rm -rf node_modules",
  "title": "Permission Required",
  "notification_type": "permission"
}

​
PermissionRequest

ツール実行にユーザー認可が必要な時に発火します。 matcher： ツール名 追加入力フィールド： 
{
  "tool_name": "Bash",
  "tool_input": {"command": "rm -rf node_modules"}
}

​
シナリオ例

​
デスクトップ通知

Agent がタスクを完了した時や権限が必要な時に、デスクトップ通知を表示します。 スクリプト ~/.qoderwork/hooks/notify.sh（macOS）： 
#!/bin/bash
input=$(cat)
message=$(echo "$input" | jq -r '.message')

if echo "$message" | grep -q "^Agent"; then
  osascript -e 'display notification "タスク完了" with title "QoderWork"'
else
  osascript -e 'display notification "権限が必要です" with title "QoderWork"'
fi

exit 0
設定： 
{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/notify.sh"
          }
        ]
      }
    ]
  }
}

​
ファイル書き込み後の自動 Lint

Agent がファイルを書き込み・編集するたびに、自動で lint を実行します。 スクリプト ${project}/.qoderwork/hooks/auto-lint.sh： 
#!/bin/bash
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path')

case "$file_path" in
  *.js|*.ts|*.jsx|*.tsx)
    npx eslint "$file_path" --fix 2>/dev/null
    ;;
esac

exit 0
設定：イベント PostToolUse、matcher Write|Edit、command .qoderwork/hooks/auto-lint.sh。

​
Agent を継続させる

Agent が停止する際に未完了タスクがないかチェックし、コミットされていない git 変更がある場合は Agent の停止をブロックします。 スクリプト ~/.qoderwork/hooks/check-continue.sh： 
#!/bin/bash
if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
  echo "未コミットの変更を検出しました。git commit を完了してください" >&2
  exit 2
fi

exit 0
設定：イベント Stop、command ~/.qoderwork/hooks/check-continue.sh。