Claude Certified Architect · Модуль 1 · Урок 1.5

Перехват вызовов инструментов через hooks Agent SDK

Суть

Hooks — это код приложения, исполняемый детерминированно (100% контроль). PostToolUse-hook нормализует разнородные форматы данных до того, как их увидит модель. Перехват перед вызовом навязывает комплаенс — блокирует нарушение политики до исполнения.

Когда hook, а когда промпт

Hooks — для детерминированного комплаенса (финансы, личность, регуляторика). Промпт — для стилистики (тон, формат). Нормализацию данных лучше держать в одном централизованном PostToolUse-hook, а не размазывать по реализациям инструментов.

PostToolUse: нормализация timestamp из разных MCP-инструментов
func postToolUse(toolName string, result map[string]any) map[string]any {
	// Приводим разнородные форматы к единому виду до того, как их увидит модель.
	if ts, ok := result["timestamp"]; ok {
		result["timestamp"] = toISO8601(ts) // Unix/MM-DD-YYYY -> ISO 8601
	}
	if code, ok := result["status_code"]; ok {
		if name, ok := statusNames[code]; ok {
			result["status_code"] = name // число -> строка
		} else {
			result["status_code"] = "unknown"
		}
	}
	return result
}
Перехват перед вызовом: блок возвратов сверх лимита (контроль комплаенса)
func preToolUse(toolName string, toolInput map[string]any) GateResult {
	if toolName == "process_refund" {
		if amount, _ := toolInput["amount"].(float64); amount > 500 {
			// Блокируем до исполнения и перенаправляем на эскалацию.
			return Redirect{To: "escalate_to_manager", Reason: "refund > $500"}
		}
	}
	return Allow{}
}

Anti-patterns

ЛовушкаПочему не работаетВерный паттерн
Навязывать политику $500 через system promptПромпты вероятностны; крайние случаи проходят мимоPre-call hook читает сумму и блокирует до исполнения
Нормализовать данные внутри каждого инструментаЛогика размазана, ломается на новых инструментахОдин централизованный PostToolUse-hook нормализует всё
Использовать hooks для всего, включая стильИзбыточно для стилистикиHooks — финансы/личность/регуляторика; промпт — формат/тон

Exam traps

ЛовушкаПочему не работаетВерный паттерн
Чинить разнобой timestamp инструкцией в промптеМодель всё равно иногда ошибётся в сравнении времениPostToolUse-hook нормализует к ISO 8601
Валидация на уровне инструмента вместо pre-callИнструмент всё равно вызываетсяHook перенаправляет ещё до вызова инструмента

Практическое задание (T5)

  • Построить PostToolUse-hook: Unix → ISO 8601, числовой статус → строка, центы → форматированные доллары.
  • Построить pre-call hook: блок process_refund >$500 с перенаправлением на escalate_to_manager.
  • Тест: запрос возврата $750 — hook блокирует до исполнения.
  • Тест нормализации: мок-инструмент с Unix-временем и числовым статусом — Claude видит ISO/строку.
  • Сравнить: убрать hook, заменить промптом про $500; 20 тестов, посчитать обходы.

Проверка знаний

Агент поддержки клиентов

Три MCP-инструмента возвращают время в разных форматах (Unix, ISO 8601, MM/DD/YYYY). Claude ошибается в сравнении времени. Лучшее решение?

  • A Инструкция в system prompt считать всё как UTC ISO 8601
  • B Переписать 3 инструмента, чтобы возвращали ISO 8601
  • C Сделать PostToolUse-hook, нормализующий все выходы к ISO 8601
  • D Добавить отдельный инструмент нормализации времени

Агент поддержки клиентов

Нужно гарантировать: возврат >$500 невозможен без одобрения менеджера. Что выбрать?

  • A System prompt: возвраты >$500 всегда согласовывать с менеджером
  • B 5–8 few-shot примеров эскалации крупных возвратов
  • C Pre-call hook на process_refund: читает сумму, блокирует >$500, перенаправляет на эскалацию
  • D Валидация на уровне инструмента, возвращающая ошибку для >$500