10日で覚えるKiro CLIDay 9: Hooksとサブエージェント
books.chapter 910日で覚えるKiro CLI

Hooks とは

Hooks は、エージェントのライフサイクルやツール実行の特定のポイントでカスタムコマンドを実行するイベント駆動の自動化機能です。セキュリティバリデーション、ログ記録、自動フォーマット、コンテキスト追加など、様々な自動化パターンを実現できます。

5つのフックタイプ

フックタイプ トリガー 主な用途
agentSpawn エージェント起動時 環境情報の収集、初期化
userPromptSubmit プロンプト送信時 ルール適用、コンテキスト追加
preToolUse ツール実行前 バリデーション、ブロック
postToolUse ツール実行後 ログ記録、後処理
stop アシスタント応答完了時 テスト実行、クリーンアップ

終了コードの動作

終了コード 動作
0 成功。stdout をコンテキストに追加
2 ブロック（preToolUse のみ）。stderr をエージェントに返却
その他 警告を表示して続行

Hook の設定

Hooks はエージェント設定ファイルの hooks フィールドで定義します。

{
  "name": "secure-dev",
  "hooks": {
    "preToolUse": [
      {
        "command": "./scripts/validate-write.sh",
        "matcher": "write"
      }
    ],
    "postToolUse": [
      {
        "command": "./scripts/log-tool-usage.sh",
        "matcher": "*"
      }
    ],
    "stop": [
      {
        "command": "npm test"
      }
    ]
  }
}

matcher によるフィルタリング

matcher フィールドで、どのツールに対してフックを実行するかを指定します。

パターン マッチ対象
"write" write ツールのみ
"@git" git MCP サーバーの全ツール
"@git/status" git サーバーの status ツールのみ
"*" すべてのツール
"@builtin" 組み込みツールすべて
指定なし すべてのイベント（ユニバーサル）

注意: stop フックには matcher は使用しません。

タイムアウトとキャッシュ

{
  "hooks": {
    "preToolUse": [
      {
        "command": "./scripts/security-check.sh",
        "matcher": "shell",
        "timeout_ms": 10000,
        "cache_ttl_seconds": 300
      }
    ]
  }
}
設定 説明 デフォルト
timeout_ms タイムアウト（ミリ秒） 30000
cache_ttl_seconds キャッシュ有効期間（秒）。0 = キャッシュなし 0

cache_ttl_seconds を設定すると、同じ入力に対する結果がキャッシュされます。ただし、agentSpawn フックはキャッシュされません。

Hook が受け取るデータ

Hook は stdin で JSON データを受け取ります。

共通フィールド

{
  "hook_event_name": "preToolUse",
  "cwd": "/home/user/my-project"
}

ツール関連フック（preToolUse / postToolUse）

{
  "hook_event_name": "preToolUse",
  "cwd": "/home/user/my-project",
  "tool_name": "shell",
  "tool_input": {
    "command": "rm -rf /tmp/data"
  }
}

postToolUse の追加フィールド

{
  "hook_event_name": "postToolUse",
  "cwd": "/home/user/my-project",
  "tool_name": "write",
  "tool_input": { "path": "src/index.ts", "content": "..." },
  "tool_response": { "status": "success" }
}

実用的な Hook パターン

セキュリティバリデーション（preToolUse）

危険なコマンドをブロックするフック：

#!/bin/bash
# scripts/validate-shell.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Dangerous patterns
if echo "$COMMAND" | grep -qE '(rm -rf /|sudo|chmod 777|> /dev/)'; then
  echo "BLOCKED: Dangerous command detected: $COMMAND" >&2
  exit 2
fi

exit 0

{
  "hooks": {
    "preToolUse": [
      {
        "command": "./scripts/validate-shell.sh",
        "matcher": "shell"
      }
    ]
  }
}

自動テスト実行（stop）

アシスタントの応答後に自動でテストを実行：

{
  "hooks": {
    "stop": [
      {
        "command": "npm test -- --watchAll=false 2>&1 | tail -20"
      }
    ]
  }
}

コンテキスト追加（userPromptSubmit）

プロンプト送信時にプロジェクト情報を自動付加：

#!/bin/bash
# scripts/add-context.sh
echo "Current branch: $(git branch --show-current)"
echo "Last commit: $(git log -1 --oneline)"
echo "Modified files: $(git diff --name-only | head -10)"

{
  "hooks": {
    "userPromptSubmit": [
      {
        "command": "./scripts/add-context.sh"
      }
    ]
  }
}

ツール使用ログ（postToolUse）

すべてのツール使用をログファイルに記録：

#!/bin/bash
# scripts/log-tool-usage.sh
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo "$TIMESTAMP | $TOOL" >> .kiro/tool-usage.log
exit 0

{
  "hooks": {
    "postToolUse": [
      {
        "command": "./scripts/log-tool-usage.sh",
        "matcher": "*"
      }
    ]
  }
}

環境情報の収集（agentSpawn）

エージェント起動時に環境情報をコンテキストに追加：

#!/bin/bash
# scripts/collect-env.sh
echo "Node.js: $(node --version)"
echo "npm: $(npm --version)"
echo "Git branch: $(git branch --show-current)"
echo "Docker: $(docker --version 2>/dev/null || echo 'not installed')"

flowchart TB
    subgraph Lifecycle["エージェントライフサイクル"]
        Spawn["agentSpawn<br/>起動時"]
        Prompt["userPromptSubmit<br/>プロンプト送信"]
        Pre["preToolUse<br/>ツール実行前"]
        Tool["ツール実行"]
        Post["postToolUse<br/>ツール実行後"]
        Stop["stop<br/>応答完了"]
    end
    Spawn --> Prompt
    Prompt --> Pre
    Pre -->|"exit 0: 許可"| Tool
    Pre -->|"exit 2: ブロック"| Block["実行中止"]
    Tool --> Post
    Post --> Stop
    style Spawn fill:#3b82f6,color:#fff
    style Prompt fill:#8b5cf6,color:#fff
    style Pre fill:#f59e0b,color:#fff
    style Tool fill:#22c55e,color:#fff
    style Post fill:#22c55e,color:#fff
    style Stop fill:#ef4444,color:#fff
    style Block fill:#ef4444,color:#fff

サブエージェント

サブエージェントは、複雑なタスクを自律的に実行する専門エージェントです。独自のコンテキストとツールアクセスを持ち、メインエージェントから独立して動作します。

サブエージェントの特徴

特徴 説明
自律実行 エージェント設定に基づいて独立動作
リアルタイム進捗 実行中のステータスを逐次表示
ツールアクセス ファイル操作、コマンド実行、MCP ツール
並列実行 最大4つのサブエージェントを同時実行
結果集約 完了後にメインエージェントへ結果を返却

サブエージェントの実行フロー

  1. タスク割り当て — タスクを説明すると、Kiro がサブエージェントの使用を判断
  2. 初期化 — 独自のコンテキストと設定済みツールでサブエージェントが起動
  3. 自律実行 — 独立して作業（権限が必要な場面では確認を要求）
  4. 進捗報告 — リアルタイムでステータスを表示
  5. 結果返却 — 完了した結果をメインエージェントに返す

利用可能なツール

使用可能: read, write, shell, code intelligence, MCP ツール

使用不可: web_search, web_fetch, introspect, thinking, todo_list, use_aws, grep, glob

サブエージェントの制御

エージェント設定で、使用できるサブエージェントを制限できます。

{
  "toolsSettings": {
    "subagent": {
      "availableAgents": ["docs-writer", "test-runner", "code-analyzer"],
      "trustedAgents": ["test-runner"]
    }
  }
}
設定 説明
availableAgents サブエージェントとして使用可能なエージェント（グロブパターン対応）
trustedAgents 確認なしで実行を許可するエージェント

実用例

> テストカバレッジのレポートを生成しながら、同時にドキュメントも更新してください

この指示に対し、Kiro はテスト実行とドキュメント更新を別々のサブエージェントに委任し、並列で実行します。

Delegate 機能

Delegate はバックグラウンドで非同期にタスクを実行する機能です。サブエージェントと似ていますが、メインの会話をブロックしない点が異なります。

> バックグラウンドでプロジェクト全体のリンターを実行してください

Kiro は Delegate を使ってバックグラウンドでタスクを起動し、メインの会話を続けられます。完了したら通知が届きます。

まとめ

項目 内容
Hooks イベント駆動のカスタムコマンド実行
5つのタイプ agentSpawn, userPromptSubmit, preToolUse, postToolUse, stop
exit code 2 preToolUse でツール実行をブロック
matcher ツールのフィルタリング（ワイルドカード対応）
サブエージェント 自律的な専門エージェント、最大4並列
制御 availableAgents / trustedAgents
Delegate バックグラウンドでの非同期タスク実行

Day 10 では、設定管理、ACP、実践ワークフローを学びます。