Bot Hooks

Bot Hooks を使うと、ツール呼び出し、会話の turn、メモリ、ワークスペースの活動、承認、圧縮、subagent といったフローの前後で、Bot に小さな自動化ルールを実行させられます。各 Bot は自分専用の設定ファイルを持ちます:

/data/.memoh/hooks.json

Bot の詳細ページを開いて Hooks タブに進むと、このファイルを UI から編集できます。

---

Hooks タブ

Hooks タブは、Bot の hook 設定の JSON エディターです。できることは次のとおりです:

• /data/.memoh/hooks.json が存在するかの表示
• ユーザー設定が有効かの表示
• 有効な hook と action の数の集計
• サポートされているイベントカタログの一覧表示
• どのイベントがランタイムに接続済みかの表示
• JSON 設定の再読み込みと保存
• スターターテンプレートの挿入
• 合成イベント 1 件で現在の effective hooks 設定をテスト

ファイルが存在しない場合、UI とサービスは有効状態の空の設定を作成します:

{
  "version": 1,
  "enabled": true,
  "hooks": []
}

このタブにビジュアルなルールビルダーはありません。JSON を直接編集する必要があります。

---

設定の構造

{
  "version": 1,
  "enabled": true,
  "defaults": {
    "timeout": "10s",
    "on_error": "fail",
    "max_output_bytes": 65536,
    "trigger_nested_hooks": false
  },
  "env": {
    "HOOK_LOG": "/data/.memoh/hooks.log"
  },
  "hooks": [
    {
      "name": "review shell commands",
      "event": "PreToolUse",
      "matcher": "^exec$",
      "enabled": true,
      "priority": 10,
      "actions": [
        {
          "type": "command",
          "command": "python3 /data/.memoh/review-command.py",
          "timeout": "5s",
          "on_error": "block"
        }
      ]
    }
  ]
}

トップレベルのフィールド:

フィールド	説明
version	必須の schema バージョン。現在のバージョンは 1 です。
enabled	このユーザー設定ファイル内の hooks を有効化・無効化します。デフォルトは true です。
defaults.timeout	デフォルトの action タイムアウト。10s のような Go duration と、整数の秒数の両方をサポートします。デフォルトは 10s です。
defaults.on_error	デフォルトのエラー処理: ignore、fail、block のいずれか。デフォルトは fail です。
defaults.max_output_bytes	command action 1 つあたりで捕捉する stdout/stderr の最大バイト数。デフォルトは 65536 です。
defaults.trigger_nested_hooks	schema はこのフィールドを解析し、デフォルトは false です。Hooks UI には現在、専用のコントロールはありません。
env	ユーザー設定内の command action が使う追加の環境変数。
hooks	ルールのリスト。マッチした hook は priority の高い順に実行され、同じ優先度ではファイル内の順序が保たれます。

Hook のフィールド:

フィールド	説明
name	任意の表示／デバッグ用の名前。
event	必須。イベントカタログにある名前でなければなりません。
matcher	任意の正規表現。リクエスト内の最適なターゲットテキストに対してマッチします。
enabled	この hook を有効化・無効化します。デフォルトは true です。
priority	数字が大きいほど先に実行されます。
actions	hook がマッチしたときに実行する action。
conditions	schema 内では将来の拡張用に予約されています。現在のマッチングは event、enabled、matcher を使います。

matcher のターゲットテキストは、hook リクエストから次の順序で選ばれます:

• tool.name
• approval.tool_name
• channel.platform
• memory.scope
• extra.command、extra.path、extra.operation、または extra.scope
• イベント名

---

Action の種類

現在サポートされている action は command と tool の 2 種類です。

Command Action

{
  "type": "command",
  "command": "mkdir -p .memoh && cat >> .memoh/hooks.log",
  "work_dir": "/data",
  "timeout": "10s",
  "on_error": "ignore"
}

command action は Bot のワークスペースコンテナ内で実行されます。hook リクエストは JSON として stdin から渡され、末尾に改行が付きます。

作業ディレクトリの解決順序:

1. action.work_dir
2. リクエスト内のワークスペース CWD
3. /data

環境変数には次が含まれます:

• 現在の設定のトップレベルにある env
• MEMOH_HOOK_EVENT
• MEMOH_HOOK_NAME
• MEMOH_BOT_ID
• MEMOH_SESSION_ID

stdout が JSON の場合、command は次を返せます:

{
  "decision": "append_context",
  "reason": "extra context added",
  "append_context": "Use the production-safe command variant.",
  "metadata": {
    "source": "hook"
  }
}

stdout が JSON でない場合、Memoh はその action を allow として扱い、生の stdout を action metadata に格納します。非ゼロの終了コードは action エラーと見なされます。

Tool Action

{
  "type": "tool",
  "tool": "record_event",
  "input": {
    "source": "hook"
  },
  "timeout": "10s",
  "on_error": "fail"
}

tool action は、利用可能な Bot ツールを名前で呼び出し、設定にある input を渡します。ツールの結果がオブジェクトの場合、decision、reason、append_context を返せます。

mcp_tool はコード内では予約された型ですが、現在は拒否されます。

---

決定とエラー

action は次の decision を返せます:

Decision	効果
allow	通常どおり続行します。
deny	ガード対象の操作を拒否します。PreToolUse の場合、そのツール呼び出しを拒否します。
ask_approval	ランタイムが承認の引き継ぎをサポートしている箇所で、人間による承認を要求します。
append_context	イベントの接続点が append_context を消費する場合にコンテキストを追加します。たとえば prompt、model、memory 関連のフローです。

on_error は action が失敗したときの挙動を制御します:

値	効果
ignore	記録して、次の action に進みます。
fail	action エラーを返します。デフォルト値です。
block	失敗を deny decision に変換します。

---

イベントカタログ

Hooks タブは /bots/{bot_id}/hooks/events からイベントカタログを読み込みます。runtime-supported とマークされたイベントは、現在の実行パスに接続済みです。catalog-only のイベントは設定の解析とテストインターフェースを通りますが、現時点ではそれらを発行する実際のランタイムパスはありません。

Event	領域	ランタイム接続済み	説明
PreToolUse	ツール	はい	ツール呼び出しの承認決定の前に実行されます。拒否や承認の要求ができます。
PostToolUse	ツール	はい	ツール呼び出しの成功後に実行されます。
ToolError	ツール	はい	ツール呼び出しがエラーを返したときに実行されます。
SessionStart	セッション	はい	セッションの作成後に実行されます。
UserMessageReceived	会話	はい	conversation resolver がユーザーメッセージを受け取った後に実行されます。
BeforePromptBuild	Prompt	はい	prompt の組み立て前に実行されます。append_context を system prompt に追加できます。
AfterPromptBuild	Prompt	はい	prompt の組み立て後に実行されます。append_context を system prompt に追加できます。
BeforeModelCall	モデル	はい	モデルの生成 step の前に実行されます。append_context を user message として追加できます。
AfterModelCall	モデル	はい	モデルの生成 step の後に実行されます。
TurnEnd	Turn	はい	1 つの turn が完了したときに実行されます。
TurnError	Turn	はい	1 つの turn が失敗したときに実行されます。
BeforeMemorySearch	メモリ	はい	メモリ検索の前に実行されます。
AfterMemorySearch	メモリ	はい	メモリ検索の後に実行されます。append_context をメモリコンテキストにマージできます。
BeforeMemoryWrite	メモリ	はい	会話メモリの書き込み前に実行されます。
AfterMemoryWrite	メモリ	はい	メモリの書き込み後に実行されます。
MemoryExtracted	メモリ	はい	メモリの抽出／書き込み準備の完了後に実行されます。
WorkspaceStart	Workspace	はい	ワークスペースの起動後に実行されます。
WorkspaceStop	Workspace	はい	ワークスペースの停止時に実行されます。
BeforeWorkspaceCommand	Workspace	はい	ワークスペースの shell コマンド実行前に実行されます。コマンドを拒否できます。
AfterWorkspaceCommand	Workspace	はい	ワークスペースの shell コマンド実行後に実行されます。
BeforeFileWrite	Workspace	はい	ファイルの書き込みと patch の前に実行されます。書き込みを拒否できます。
AfterFileWrite	Workspace	はい	ファイルの書き込みと patch の後に実行されます。
BeforeApprovalCreate	承認	はい	ツール承認リクエストの作成前に実行されます。
ApprovalRequested	承認	はい	承認リクエストの送信後に実行されます。
ApprovalResolved	承認	はい	承認が処理された後に実行されます。
ApprovalTimeout	承認	はい	承認がタイムアウトしたときに実行されます。
PreCompact	圧縮	はい	セッション圧縮の前に実行されます。
PostCompact	圧縮	はい	セッション圧縮の後に実行されます。
SubagentStart	Subagent	はい	subagent タスクの開始前に実行されます。
SubagentStop	Subagent	はい	subagent タスクの終了後に実行されます。
InboundMessageNormalized	メッセージ	いいえ	現在はイベントカタログにのみ存在します。
BeforeOutboundMessage	メッセージ	いいえ	現在はイベントカタログにのみ存在します。
AfterOutboundMessage	メッセージ	いいえ	現在はイベントカタログにのみ存在します。
ChannelDeliveryFailed	メッセージ	いいえ	現在はイベントカタログにのみ存在します。

---

Hooks のテスト

Hooks タブの Test セクションで、合成イベントを 1 件実行できます:

1. イベントを選びます。
2. JSON payload を編集します。
3. Run Test をクリックします。
4. 返ってきた結果を確認します。マッチした hooks、実行された actions、decision、action results、hook source metadata が含まれます。

テストパスは effective config を使い、action を実際に実行します。破壊的なコマンドやツール呼び出しの検証がまさに目的である場合を除き、テスト payload でそれらをトリガーしないでください。

---

セキュリティ上の注意

Hooks は Bot のワークスペース内で実際に実行されます。そこで動くコードと同じものとして扱ってください。

• 有効化する前に、すべての command action をレビューしてください。
• PreToolUse、BeforeWorkspaceCommand、BeforeFileWrite の使用には注意してください。Bot の通常の作業をブロックしてしまうことがあります。
• timeout は短く保ち、on_error を明示的に設定してください。
• 長期間有効な secrets を hooks.json に直接書かないでください。
• リスクの高い hooks には、できるだけ狭い matcher を使ってください。
• command action は stdin から hook リクエストを受け取り、そこにはメッセージテキスト、ツール入力、パス、エラー情報が含まれ得ることを覚えておいてください。

---

関連ページ

• Bot
• スキル