このページは英語版ドキュメントの翻訳です。コマンド、識別子、例はそのままです。ランタイム 7.24.4 · SDK 2.6.7。英語版

ライフサイクルフック

状態: 有効範囲: 現行状態最終確認: 2026-08-23 担当: ax-code ランタイム

ライフサイクルフックを使うと、ランタイムを再ビルドせずに、エージェントのイベントでシェルコマンドを実行できます。権限ルールと分離サンドボックスを補います。フックは決定的な副作用（「常にフォーマットする」「強制プッシュは決してしない」）であり、プロンプトは助言のままです。

イベント

イベント	いつ	ブロックできるか
PreToolUse	ツールが実行される前	はい（`blockOnFailure: true`）
PostToolUse	ツールが完了したあと（`args`: ツール引数）。上限付きの標準出力または構造化されたフィードバックが、モデルが見るツール結果に追加されます。下記を参照	いいえ
PostToolUseFailure	ツールが例外を投げたあと（`args`: `{ args, error }`、エラーテキストは 4,000 文字で上限）。送りっぱなしです。エラーは変わらずモデルに届きます	いいえ
Stop	セッションのターンが完了したとき（パックは自動化を通して停止時に走ることがあります）	いいえ
UserPromptSubmit	ユーザープロンプトが送信され、メッセージが永続化される前	はい（`blockOnFailure: true`）
PreCompact	セッションのコンパクションが走る前（`args`: `{ auto, overflow }`）	いいえ
SubagentStop	`task` サブエージェントが終わったとき（`args`: `{ agent, status }`）	いいえ
SessionStart	最上位セッションが作られたとき（`args`: `{ sessionID, title, time }`）	いいえ
SessionEnd	セッションが削除またはアーカイブされたとき（`args`: `{ sessionID, reason }`、`reason` は `"remove"` または `"archive"`）	いいえ
PostCompact	セッションのコンパクションが成功して完了したあと（`args`: `{ sessionID, reason }`、`reason` は `"auto"` または `"manual"`。コンパクションが中断したとき、たとえばコンテキストあふれでは発火しません）	いいえ
Interrupt	ユーザーまたは運用者が実行中のターンを明示的に取り消したとき（`args`: `{ sessionID }`。通常のターン完了や内部の片付けでは発火しません）	いいえ

4 つのセッションライフサイクルイベント（SessionStart、SessionEnd、PostCompact、Interrupt）と PostToolUseFailure は観察のみです。発火して忘れ、ライフサイクル経路を決してブロックせず、ペイロードは識別子、理由、タイムスタンプだけを運びます。会話テキスト、要約、ツール出力は運びません。サブエージェントセッションは SessionStart を発火しません（すでに SubagentStop を通して現れます）。SubagentStop は、task と task_parallel の両方で開始された子について発火します。

PostToolUse のフィードバックはモデルに届く

PostToolUse フックは、テキストをモデルへ戻せます。ツール自身の出力のあと、<hook_feedback event="PostToolUse"> ブロックの中でツール結果に追加されます。出力を置き換えず、ブロックもしません。

レガシー項目（protocol なし）: 終了コード 0 のフックの、トリムされた標準出力。
protocol: "claude-code" 項目: hookSpecificOutput.additionalContext、reason（{"decision": "block", "reason": "..."} 判定のもの）、またはフックが終了コード 2 のときの標準エラー。その他の非ゼロ終了は何も寄与しません。

フィードバックはフックあたり 4,000 文字、ツール呼び出しあたり 8,000 文字で上限されるため、騒がしいフックがコンテキストをあふれさせることはできません。これが format-after-edit パックを有用にします。その注意はログだけでなく、モデルの次のターンに届きます。

これらの名前は、AX Code 内部のプラグイントリガー（tool.execute.before / tool.execute.after）に加え、セッションレベルのプロンプト、コンパクション、サブエージェント、停止フックへ対応します。合成の継続プロンプト（内部の agentRouting: "preserve" プロンプト）は UserPromptSubmit を発火しません。

パックを有効にする

プロジェクトのフックとプラグインはリポジトリが制御するコードを実行するため、.ax-code/hooks.json、.ax-code/plugin/、およびプロジェクト設定のプラグインは既定で無効です。レビューしたあと、AX Code を起動するときにリポジトリの外でオプトインします。

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

そのあと、プロジェクトに .ax-code/hooks.json を作ります。

{
  "packs": ["format-after-edit", "block-force-push", "require-tests-on-stop", "protect-env-files", "log-bash-commands"]
}

公式パック（5 以上）

パック	イベント	説明
`format-after-edit`	PostToolUse	編集後にフォーマットするようエージェントへ思い出させます
`block-force-push`	PreToolUse	`git push --force` / `-f` をブロックします
`require-tests-on-stop`	Stop	変更後に検証するよう思い出させます
`protect-env-files`	PreToolUse	ツールが `.env` に触れるときに警告します
`log-bash-commands`	PreToolUse	監査のため bash コマンドを記録します

カスタムフック:

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "echo running bash",
      "blockOnFailure": false
    }
  ]
}

Claude Code のワイヤプロトコル（オプトイン）

すでに Claude Code 向けに書かれたフックがある場合、項目は "protocol": "claude-code" で Claude Code のワイヤプロトコルへオプトインできます。

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "my-claude-code-hook.sh",
      "protocol": "claude-code"
    }
  ]
}

ブロックできるイベント（PreToolUse、UserPromptSubmit）では、オプトインした項目は blockOnFailure 確認の代わりに、Claude Code の意味で復号されます。

終了 2 は動作をブロックします。フックの標準エラーが理由として示されます。不正な標準出力もブロックします（フェイルセーフ）。
終了 0 で標準出力 JSON が {"permissionDecision": "allow"|"deny"|"ask", "reason"?} のとき: allow は続行します。deny は reason でブロックします。ask は、理由を示す対話的な hook 権限プロンプトでツール呼び出しを一時停止します（既定は "hook requested user confirmation"）。プロンプトは対話のみです。always ルール、ワイルドカード付与、自律の自動承認はそれに答えられず、ヘッドレス実行は拒否します。モデルはそれを通常の権限拒否として見ます。後のフックが deny と答えると、より早い ask に勝ちます。UserPromptSubmit にはプロンプトを付けるツール呼び出しがないため、そこでは ask が依然としてブロックします。入れ子の Claude Code 形 {"hookSpecificOutput": {"permissionDecision": "...", "permissionDecisionReason": "..."}} は別名として受け付けられます。
その他の終了 は非ブロックのエラーです（記録され、動作は続行します）。

観察のみのイベントはデコーダを完全に無視します。決してブロックできません。protocol フィールドのない項目は、以前とまったく同じように振る舞います。

フックコマンドが使える環境変数:

HOOK_EVENT — 取り得る値は PreToolUse、PostToolUse、PostToolUseFailure、Stop、UserPromptSubmit、PreCompact、SubagentStop、SessionStart、SessionEnd、PostCompact、Interrupt です
HOOK_TOOL — ツールの識別子
HOOK_SESSION_ID
HOOK_ARGS_JSON — JSON のツール引数
HOOK_ARGS_STDIN=1 — 完全な JSON 引数は常に標準入力で利用できます。ペイロードが 32 KiB より大きいとき、HOOK_ARGS_JSON は空です
HOOK_PACK — 該当する場合のパック名

フックの子プロセスは、AX Code 環境の無害化された版を継承します。AX Code は通常のプラットフォームとツールの変数を保持しますが、秘密らしい名前、資格情報を含む URL、SSH_AUTH_SOCK のような資格情報ヘルパー、NODE_OPTIONS のようなプロセス注入変数を取り除きます。上記の HOOK_* プロトコル変数は無害化のあとに追加され、常に利用できます。

周囲の資格情報を必要とする、完全に信頼されたレガシーフックは、リポジトリの外で以前の振る舞いを戻せます。

AX_CODE_HOOKS_FULL_ENV=1 AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

この逃げ道は、有効なすべてのフックへすべての環境変数を露出します。リポジトリは .ax-code/hooks.json を通してそれを要求できません。すべてのフックとパックをレビューしたあとだけ使ってください。

セキュリティ上の注意: 環境の無害化は周囲の資格情報露出を減らしますが、フックコマンドをサンドボックスしません。フックは、アクセス可能なファイルを読み、ホストのネットワークを使える任意のシェルコードのままです。信頼されたコードとして扱い、有効なすべてのフックとパックをレビューしてください。

分離との関係

フックはサンドボックスを置き換えません。次を使ってください。

移植可能な書き込みとネットワークの境界には アプリ分離
利用できるときの、カーネルが強制する bash サンドボックスには OS 分離（既定の "auto" バックエンド）
強制プッシュのようなポリシーの副作用と硬いブロックには フック

サンドボックスモードと SECURITY.md を参照してください。