フックを使用してエージェントの動作をインターセプトして制御する

import asyncio
from claude_agent_sdk import (
    AssistantMessage,
    ClaudeSDKClient,
    ClaudeAgentOptions,
    HookMatcher,
    ResultMessage,
)


# ツール呼び出しの詳細を受け取るフックコールバックを定義する
async def protect_env_files(input_data, tool_use_id, context):
    # ツールの入力引数からファイルパスを抽出する
    file_path = input_data["tool_input"].get("file_path", "")
    file_name = file_path.split("/")[-1]

    # .env ファイルをターゲットにしている場合は操作をブロックする
    if file_name == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }

    # 空のオブジェクトを返して操作を許可する
    return {}


async def main():
    options = ClaudeAgentOptions(
        hooks={
            # PreToolUse イベントのフックを登録する
            # マッチャーは Write と Edit ツール呼び出しのみにフィルタリングする
            "PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]
        }
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Update the database configuration")
        async for message in client.receive_response():
            # アシスタントとリザルトメッセージをフィルタリングする
            if isinstance(message, (AssistantMessage, ResultMessage)):
                print(message)


asyncio.run(main())

import { query, HookCallback, PreToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";

// HookCallback 型でフックコールバックを定義する
const protectEnvFiles: HookCallback = async (input, toolUseID, { signal }) => {
  // 型安全性のために入力を特定のフック型にキャストする
  const preInput = input as PreToolUseHookInput;

  // tool_input をキャストしてそのプロパティにアクセスする（SDK では unknown として型付けされている）
  const toolInput = preInput.tool_input as Record<string, unknown>;
  const filePath = toolInput?.file_path as string;
  const fileName = filePath?.split("/").pop();

  // .env ファイルをターゲットにしている場合は操作をブロックする
  if (fileName === ".env") {
    return {
      hookSpecificOutput: {
        hookEventName: preInput.hook_event_name,
        permissionDecision: "deny",
        permissionDecisionReason: "Cannot modify .env files"
      }
    };
  }

  // 空のオブジェクトを返して操作を許可する
  return {};
};

for await (const message of query({
  prompt: "Update the database configuration",
  options: {
    hooks: {
      // PreToolUse イベントのフックを登録する
      // マッチャーは Write と Edit ツール呼び出しのみにフィルタリングする
      PreToolUse: [{ matcher: "Write|Edit", hooks: [protectEnvFiles] }]
    }
  }
})) {
  // アシスタントとリザルトメッセージをフィルタリングする
  if (message.type === "assistant" || message.type === "result") {
    console.log(message);
  }
}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[my_callback])]}
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Your prompt")
    async for message in client.receive_response():
        print(message)

for await (const message of query({
  prompt: "Your prompt",
  options: {
    hooks: {
      PreToolUse: [{ matcher: "Bash", hooks: [myCallback] }]
    }
  }
})) {
  console.log(message);
}

async def async_hook(input_data, tool_use_id, context):
    # バックグラウンドタスクを開始してから即座に返す
    asyncio.create_task(send_to_logging_service(input_data))
    return {"async_": True, "asyncTimeout": 30000}

const asyncHook: HookCallback = async (input, toolUseID, { signal }) => {
  // バックグラウンドタスクを開始してから即座に返す
  sendToLoggingService(input).catch(console.error);
  return { async: true, asyncTimeout: 30000 };
};

async def redirect_to_sandbox(input_data, tool_use_id, context):
    if input_data["hook_event_name"] != "PreToolUse":
        return {}

    if input_data["tool_name"] == "Write":
        original_path = input_data["tool_input"].get("file_path", "")
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "allow",
                "updatedInput": {
                    **input_data["tool_input"],
                    "file_path": f"/sandbox{original_path}",
                },
            }
        }
    return {}

const redirectToSandbox: HookCallback = async (input, toolUseID, { signal }) => {
  if (input.hook_event_name !== "PreToolUse") return {};

  const preInput = input as PreToolUseHookInput;
  const toolInput = preInput.tool_input as Record<string, unknown>;
  if (preInput.tool_name === "Write") {
    const originalPath = toolInput.file_path as string;
    return {
      hookSpecificOutput: {
        hookEventName: preInput.hook_event_name,
        permissionDecision: "allow",
        updatedInput: {
          ...toolInput,
          file_path: `/sandbox${originalPath}`
        }
      }
    };
  }
  return {};
};

async def block_etc_writes(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")

    if file_path.startswith("/etc"):
        return {
            # トップレベルフィールド：ユーザーに表示されるメッセージ
            "systemMessage": "Remember: system directories like /etc are protected.",
            # hookSpecificOutput：操作をブロックする
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Writing to /etc is not allowed",
            },
        }
    return {}

const blockEtcWrites: HookCallback = async (input, toolUseID, { signal }) => {
  const preInput = input as PreToolUseHookInput;
  const toolInput = preInput.tool_input as Record<string, unknown>;
  const filePath = toolInput?.file_path as string;

  if (filePath?.startsWith("/etc")) {
    return {
      // トップレベルフィールド：ユーザーに表示されるメッセージ
      systemMessage: "Remember: system directories like /etc are protected.",
      // hookSpecificOutput：操作をブロックする
      hookSpecificOutput: {
        hookEventName: preInput.hook_event_name,
        permissionDecision: "deny",
        permissionDecisionReason: "Writing to /etc is not allowed"
      }
    };
  }
  return {};
};

async def auto_approve_read_only(input_data, tool_use_id, context):
    if input_data["hook_event_name"] != "PreToolUse":
        return {}

    read_only_tools = ["Read", "Glob", "Grep"]
    if input_data["tool_name"] in read_only_tools:
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "allow",
                "permissionDecisionReason": "Read-only tool auto-approved",
            }
        }
    return {}

const autoApproveReadOnly: HookCallback = async (input, toolUseID, { signal }) => {
  if (input.hook_event_name !== "PreToolUse") return {};

  const preInput = input as PreToolUseHookInput;
  const readOnlyTools = ["Read", "Glob", "Grep"];
  if (readOnlyTools.includes(preInput.tool_name)) {
    return {
      hookSpecificOutput: {
        hookEventName: preInput.hook_event_name,
        permissionDecision: "allow",
        permissionDecisionReason: "Read-only tool auto-approved"
      }
    };
  }
  return {};
};

options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(hooks=[authorization_check]),
            HookMatcher(hooks=[input_validator]),
            HookMatcher(hooks=[audit_logger]),
        ]
    }
)

const options = {
  hooks: {
    PreToolUse: [
      { hooks: [authorizationCheck] },
      { hooks: [inputValidator] },
      { hooks: [auditLogger] }
    ]
  }
};

options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            # ファイル変更ツールをマッチングする
            HookMatcher(matcher="Write|Edit|Delete", hooks=[file_security_hook]),
            # すべての MCP ツールをマッチングする
            HookMatcher(matcher="^mcp__", hooks=[mcp_audit_hook]),
            # すべてをマッチングする（マッチャーなし）
            HookMatcher(hooks=[global_logger]),
        ]
    }
)

const options = {
  hooks: {
    PreToolUse: [
      // ファイル変更ツールをマッチングする
      { matcher: "Write|Edit|Delete", hooks: [fileSecurityHook] },

      // すべての MCP ツールをマッチングする
      { matcher: "^mcp__", hooks: [mcpAuditHook] },

      // すべてをマッチングする（マッチャーなし）
      { hooks: [globalLogger] }
    ]
  }
};

async def subagent_tracker(input_data, tool_use_id, context):
    # サブエージェントが完了したときにサブエージェント詳細をログする
    print(f"[SUBAGENT] Completed: {input_data['agent_id']}")
    print(f"  Transcript: {input_data['agent_transcript_path']}")
    print(f"  Tool use ID: {tool_use_id}")
    print(f"  Stop hook active: {input_data.get('stop_hook_active')}")
    return {}


options = ClaudeAgentOptions(
    hooks={"SubagentStop": [HookMatcher(hooks=[subagent_tracker])]}
)

import { HookCallback, SubagentStopHookInput } from "@anthropic-ai/claude-agent-sdk";

const subagentTracker: HookCallback = async (input, toolUseID, { signal }) => {
  // SubagentStopHookInput にキャストしてサブエージェント固有のフィールドにアクセスする
  const subInput = input as SubagentStopHookInput;

  // サブエージェントが完了したときにサブエージェント詳細をログする
  console.log(`[SUBAGENT] Completed: ${subInput.agent_id}`);
  console.log(`  Transcript: ${subInput.agent_transcript_path}`);
  console.log(`  Tool use ID: ${toolUseID}`);
  console.log(`  Stop hook active: ${subInput.stop_hook_active}`);
  return {};
};

const options = {
  hooks: {
    SubagentStop: [{ hooks: [subagentTracker] }]
  }
};

import asyncio
import json
import urllib.request
from datetime import datetime


def _send_webhook(tool_name):
    """外部ウェブフックにツール使用データを POST する同期ヘルパー。"""
    data = json.dumps(
        {
            "tool": tool_name,
            "timestamp": datetime.now().isoformat(),
        }
    ).encode()
    req = urllib.request.Request(
        "https://api.example.com/webhook",
        data=data,
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    urllib.request.urlopen(req)


async def webhook_notifier(input_data, tool_use_id, context):
    # ツールが完了した後（PostToolUse）に発火し、前ではない
    if input_data["hook_event_name"] != "PostToolUse":
        return {}

    try:
        # イベントループをブロックしないようにスレッドでブロッキング HTTP 呼び出しを実行する
        await asyncio.to_thread(_send_webhook, input_data["tool_name"])
    except Exception as e:
        # エラーをログするが、発生させない。失敗したウェブフックはエージェントを停止すべきではない
        print(f"Webhook request failed: {e}")

    return {}

import { query, HookCallback, PostToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";

const webhookNotifier: HookCallback = async (input, toolUseID, { signal }) => {
  // ツールが完了した後（PostToolUse）に発火し、前ではない
  if (input.hook_event_name !== "PostToolUse") return {};

  try {
    await fetch("https://api.example.com/webhook", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        tool: (input as PostToolUseHookInput).tool_name,
        timestamp: new Date().toISOString()
      }),
      // フックがタイムアウトした場合、リクエストがキャンセルされるように signal を渡す
      signal
    });
  } catch (error) {
    // キャンセルを他のエラーから分けて処理する
    if (error instanceof Error && error.name === "AbortError") {
      console.log("Webhook request cancelled");
    }
    // 再スローしない。失敗したウェブフックはエージェントを停止すべきではない
  }

  return {};
};

// PostToolUse フックとして登録する
for await (const message of query({
  prompt: "Refactor the auth module",
  options: {
    hooks: {
      PostToolUse: [{ hooks: [webhookNotifier] }]
    }
  }
})) {
  console.log(message);
}

import asyncio
import json
import urllib.request

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher


def _send_slack_notification(message):
    """受信ウェブフック経由で Slack にメッセージを送信する同期ヘルパー。"""
    data = json.dumps({"text": f"Agent status: {message}"}).encode()
    req = urllib.request.Request(
        "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
        data=data,
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    urllib.request.urlopen(req)


async def notification_handler(input_data, tool_use_id, context):
    try:
        # イベントループをブロックしないようにスレッドでブロッキング HTTP 呼び出しを実行する
        await asyncio.to_thread(_send_slack_notification, input_data.get("message", ""))
    except Exception as e:
        print(f"Failed to send notification: {e}")

    # 空のオブジェクトを返す。通知フックはエージェント動作を変更しない
    return {}


async def main():
    options = ClaudeAgentOptions(
        hooks={
            # 通知イベントのフックを登録する（マッチャーは不要）
            "Notification": [HookMatcher(hooks=[notification_handler])],
        },
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Analyze this codebase")
        async for message in client.receive_response():
            print(message)


asyncio.run(main())

import { query, HookCallback, NotificationHookInput } from "@anthropic-ai/claude-agent-sdk";

// 通知を Slack に送信するフックコールバックを定義する
const notificationHandler: HookCallback = async (input, toolUseID, { signal }) => {
  // NotificationHookInput にキャストして message フィールドにアクセスする
  const notification = input as NotificationHookInput;

  try {
    // 通知メッセージを Slack 受信ウェブフックに POST する
    await fetch("https://hooks.slack.com/services/YOUR/WEBHOOK/URL", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        text: `Agent status: ${notification.message}`
      }),
      // フックがタイムアウトした場合、リクエストがキャンセルされるように signal を渡す
      signal
    });
  } catch (error) {
    if (error instanceof Error && error.name === "AbortError") {
      console.log("Notification cancelled");
    } else {
      console.error("Failed to send notification:", error);
    }
  }

  // 空のオブジェクトを返す。通知フックはエージェント動作を変更しない
  return {};
};

// 通知イベントのフックを登録する（マッチャーは不要）
for await (const message of query({
  prompt: "Analyze this codebase",
  options: {
    hooks: {
      Notification: [{ hooks: [notificationHandler] }]
    }
  }
})) {
  console.log(message);
}

options = ClaudeAgentOptions(
    setting_sources=["project"],  # フックを含む .claude/settings.json をロード
)

const options = {
  settingSources: ["project"] // フックを含む .claude/settings.json をロード
};