Kiro CLI 2.13 V3モードの新機能 Introspect Subagent / Global Hooks を試してみた

はじめに

Kiro CLI 2.13.0（2026年7月17日リリース）で、早期アクセスとして提供されている V3 モードに「Introspect Subagent」と「Global Hooks」が追加されました。

https://kiro.dev/changelog/cli/2-13/

V2 ではフックをエージェントの JSON 内に定義していましたが、V3 では独立した JSON ファイルとして定義する新形式が導入されています（移行期間中はエージェント設定内の既存フックも引き続き動作します）。主な変更点を次の表にまとめます。

本記事では、Introspect でフック仕様を確認し、ローカル／グローバルフックの発火と exit 2 によるブロックまでを検証します。

検証環境

Introspect Subagent でフック仕様を確認する

V2 の introspect ツールはドキュメント検索型でしたが、V3 ではサブエージェントとして応答する方式に変わっています。V3 セッション内で「V3のフック定義のJSONスキーマを教えて」と質問し、Introspect Subagent がフック仕様の詳細を返すことを確認しました。

取得できた JSON スキーマです。

{
  "version": "v1",
  "hooks": [
    {
      "name": "...",
      "trigger": "...",
      "matcher": "...",
      "action": {
        "type": "command",
        "command": "..."
      }
    }
  ]
}

Introspect は以下も回答しました（後述のとおり一部不正確な点を含みます）。

• トリガー10種（PascalCase）: PreToolUse, PostToolUse, SessionStart, Stop, UserPromptSubmit, PreTaskExec, PostTaskExec, PostFileCreate, PostFileSave, PostFileDelete
• アクションタイプ: command（シェルコマンド実行）と agent（プロンプトをモデルコンテキストに追加）
• Exit Code: 0=成功（stdout転送）、2=ブロック（stderr転送）、その他=サイレント失敗
• matcher: PreToolUse / PostToolUse はツール名の正規表現、PostFileCreate / PostFileSave / PostFileDelete はファイルパスの正規表現

公式ドキュメントと照合すると、Introspect の回答にはいくつか不正確な点がありました。トリガーは Manual（ユーザーが任意に実行）を含む11種です。Exit Code の挙動も、公式では exit 0 の stdout がコンテキストに追加されるのは SessionStart と UserPromptSubmit のみで、その他のトリガーでは無視されます。exit 2 で実行をブロックできるのは PreToolUse と UserPromptSubmit です（Trigger reference 表では PreTaskExec もブロック可能）。また、0 / 2 以外の終了コードはサイレント失敗ではなく、警告がユーザーに表示されて処理が続行されます。

なお、上記トリガーのうち PreToolUse, PostToolUse, UserPromptSubmit は後述の検証で発火を確認しました。SessionStart もフック発火を確認しましたが、stdout は画面に表示されず LLM コンテキストへ追加される挙動でした（公式ドキュメントの Exit Code 仕様と一致します）。残りのトリガーは今回未検証です。

ローカルフックの動作確認（PreToolUse / PostToolUse / UserPromptSubmit）

V3 形式（独立JSON version: "v1"）でローカルフック3本を .kiro/hooks/ に定義し、書き込み操作で発火を確認しました。

代表例として、書き込みを監査する PreToolUse フックの定義とスクリプトを示します。

.kiro/hooks/local-write-audit.json:

{
  "version": "v1",
  "hooks": [
    {
      "name": "Audit file writes (local)",
      "trigger": "PreToolUse",
      "matcher": "write",
      "action": {
        "type": "command",
        "command": "./scripts/local-write-audit.sh"
      }
    }
  ]
}

scripts/local-write-audit.sh:

#!/bin/bash
EVENT=$(cat)
FILE=$(echo "$EVENT" | jq -r '.tool_input.path // .tool_input.operations[0].path // "unknown"')
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
echo "[$TIMESTAMP] [LOCAL] write → $FILE" >> ./logs/local-audit.log
exit 0

書き込み操作を依頼した結果です。

[2026-07-20 22:13:44] [LOCAL] write → /home/user/project/test-local.txt

今回のイベント JSON ではツール名として fs_write が渡されました。matcher にアンカーを付けず "write" と指定したところ、fs_write の一部に一致してフックが発火しました。

PostToolUse と UserPromptSubmit は定義 JSON と発火ログを示します。

公式ドキュメントでは matcher の Default が always-match（全ツール対象）とされています。本検証でも matcher 省略の PostToolUse フックが書き込み操作で発火しました。定義です。

.kiro/hooks/local-post-tool-log.json:

{
  "version": "v1",
  "hooks": [
    {
      "name": "Log tool completion",
      "trigger": "PostToolUse",
      "action": {
        "type": "command",
        "command": "./scripts/post-tool-log.sh"
      }
    }
  ]
}

[2026-07-20 22:13:46] PostToolUse: fs_write (status: unknown)

status: unknown はスクリプト側のフォールバック値です。イベント JSON から直接的なステータスフィールドを取得できませんでした。

.kiro/hooks/local-prompt-log.json:

{
  "version": "v1",
  "hooks": [
    {
      "name": "Log user prompts",
      "trigger": "UserPromptSubmit",
      "action": {
        "type": "command",
        "command": "./scripts/prompt-log.sh"
      }
    }
  ]
}

UserPromptSubmit はプロンプト本文を記録する目的で定義しましたが、今回の検証では、標準入力で受け取ったイベント JSON からプロンプト本文に相当するフィールドを確認できず、このスクリプトでは本文の取得に至りませんでした。取得手段が別に存在する可能性はあります。

[2026-07-20 22:13:40] Prompt: (empty)

これら3本とグローバルフック（後述）を同時に有効化した状態で、1回の書き込み操作における発火順序を確認しました。

UserPromptSubmit (22:13:40)
  → PreToolUse [GLOBAL] (22:13:44)
  → PreToolUse [LOCAL] (22:13:44)
  → ツール実行
  → PostToolUse (22:13:46)

グローバルフックの動作確認

~/.kiro/hooks/ にフック定義 JSON を配置するだけで、プロジェクト側に設定がなくても発火することを確認しました。書き込み監査と .env ブロックを1本にまとめたフックを定義しています。

~/.kiro/hooks/global-write-audit.json:

{
  "version": "v1",
  "hooks": [
    {
      "name": "Global write audit",
      "trigger": "PreToolUse",
      "matcher": "write",
      "action": {
        "type": "command",
        "command": "~/.kiro/hooks/scripts/write-audit.sh"
      }
    }
  ]
}

~/.kiro/hooks/scripts/write-audit.sh:

#!/bin/bash
EVENT=$(cat)
FILE=$(echo "$EVENT" | jq -r '.tool_input.path // .tool_input.operations[0].path // "unknown"')
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
echo "[$TIMESTAMP] [GLOBAL] write → $FILE" >> /tmp/kiro-v3-global-audit.log

if echo "$FILE" | grep -qE '\.env$'; then
  echo "❌ [Global Hook] .env ファイルへの書き込みはセキュリティポリシーでブロックされました" >&2
  exit 2
fi
exit 0

通常の書き込みでは、グローバル監査ログに対象パスが記録されました。

[2026-07-20 22:13:44] [GLOBAL] write → /home/user/project/test-local.txt

別ワークスペースでも動作するか、.kiro/hooks/ が存在しない /tmp から起動して確認しました。

[2026-07-20 22:17:18] [GLOBAL] write → /tmp/test-tmp.txt

ローカルフックは発火せず、グローバルフックのみが発火しました。プロジェクト側に何も置かなくても、ホームディレクトリのフックが効くことを確認できました。

ローカルフックとの共存も確認しました。同一操作でグローバル・ローカル両方が同一秒に発火しています。

• グローバルログ: [2026-07-20 22:13:44] [GLOBAL] write → /home/user/project/test-local.txt
• ローカルログ: [2026-07-20 22:13:44] [LOCAL] write → /home/user/project/test-local.txt

同じトリガー（PreToolUse）と同じ matcher（write）を持つグローバル・ローカル両方のフックが発火します。

exit 2 による .env 書き込みブロック

V3 セッションで .env ファイルの作成を依頼すると、監査ログに書き込み対象が記録されたうえで、書き込みがブロックされました。

[2026-07-20 22:14:28] [GLOBAL] write → /home/user/project/.env

V3 の画面表示は次のようになりました。

● Write /home/user/project/.env
    Tool execution failed

V3 の画面上では Tool execution failed と表示されました（前回検証した V2 では PreToolHook blocked the tool execution という表示でした）。exit 2 の stderr が LLM へ返される点は V2・V3 共通の公式仕様ですが、今回の V3 セッションでは LLM がその内容をもとにブロック理由をユーザーに説明しました。

.env ファイルへの書き込みがセキュリティポリシーによりブロックされました。このワークスペースでは .env ファイルの作成が制限されているようです。

実際に .env ファイルは作成されておらず、ブロックが正しく機能しています。

まとめ

Kiro CLI の V3 モードでは、Introspect Subagent や Global Hooks の追加により、CLI 上での仕様確認やツール実行前後の制御が少しずつ強化されています。

今回の検証では、V3 形式のフック定義を使って、ローカルフックとグローバルフックの発火、さらに exit 2 による .env 書き込みブロックを確認できました。特に Global Hooks は、~/.kiro/hooks/ に配置するだけで、そのユーザーの V3 セッションで開いた複数ワークスペースに共通ルールを適用できるため、従来の steering とは別軸のガードレールとして使えそうです。

Introspect の回答には公式仕様とずれる部分もありましたが、V3 モードは着実に機能強化が進んでいる印象です。今後、フック機能や Introspect の精度がさらに改善され、Kiro CLI 上で安全に自動化を進めるための仕組みがより充実していくことに期待したいです。