Claude Certified Architect · Модуль 1 · Урок 1.5
Перехват вызовов инструментов через hooks Agent SDK
Суть
Hooks — это код приложения, исполняемый детерминированно (100% контроль). PostToolUse-hook нормализует разнородные форматы данных до того, как их увидит модель. Перехват перед вызовом навязывает комплаенс — блокирует нарушение политики до исполнения.
Когда hook, а когда промпт
Hooks — для детерминированного комплаенса (финансы, личность, регуляторика). Промпт — для стилистики (тон, формат). Нормализацию данных лучше держать в одном централизованном PostToolUse-hook, а не размазывать по реализациям инструментов.
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 ошибается в сравнении времени. Лучшее решение?
Верный ответ: C
C верно. PostToolUse-hook централизует нормализацию в одном месте — единообразно и автоматически для будущих инструментов. B работает, но требует менять чужие инструменты (часто невозможно). A вероятностно. D добавляет лишнюю нагрузку.
Агент поддержки клиентов
Нужно гарантировать: возврат >$500 невозможен без одобрения менеджера. Что выбрать?
Верный ответ: C
C верно. Pre-call hook в коде даёт детерминированную гарантию. A и B вероятностны. D всё равно вызывает инструмент — hook же перенаправляет ещё до вызова.