Бързо резюме: Claude Code hooks са автоматизационни скриптове, които се изпълняват в определени точки от жизнения цикъл по време на AI сесии за кодиране, позволявайки на разработчиците да изпълняват персонализирани команди, да валидират действия, да форматират код, да изпращат известия и да налагат правила на проекта. Тези hooks се интегрират с работния процес на Claude чрез събития като SessionStart, PreToolUse и PostToolUse, поддържащи модели на изпълнение, базирани на команди, HTTP и подкани, с конфигурируеми тайм аути и поведение на изходния код.

Системата за hooks на Claude Code превръща AI асистента за кодиране от полезен инструмент в напълно автоматизирана среда за разработка. Повечето разработчици не осъзнават степента на контрол, достъпен чрез hooks.

Ето го и въпросът - hooks не са само за изпълнение на скриптове след редакции на файлове. Те предоставят точки за прихващане през целия процес на вземане на решения на Claude. Преди да изпълни команда. След като извикването на инструмент се провали. Когато му е необходимо разрешение. Дори преди обработката на потребителски подкани.

Този наръчник обхваща всичко, което официалната документация предоставя, плюс практически модели, които дискусиите в общността разкриват, че действително работят в производствена среда.

Какво всъщност правят Claude Code Hooks

Според официалната документация на Claude Code, hooks са потребителски дефинирани shell команди, HTTP крайни точки или инжектиране на подкани, които се изпълняват в специфични точки от жизнения цикъл на Claude Code. Те получават структуриран JSON вход чрез stdin и контролират работния процес чрез изходни кодове или HTTP отговори.

Автоматизацията е по-дълбока, отколкото повечето ръководства предполагат. Hooks могат напълно да блокират изпълнението на инструменти, да инжектират допълнителен контекст в разсъжденията на Claude, да задействат външни услуги и да налагат правила за валидиране, които Claude трябва да спазва.

Съществуват три основни типа hooks:

Командни hooks: Shell скриптове, които комуникират чрез stdout, stderr и изходни кодове
HTTP hooks: Отдалечени крайни точки, които получават POST заявки и връщат JSON отговори
Hooks за подкани: Динамични инструкции, инжектирани в контекста на Claude при специфични събития

Всеки тип служи за различни модели на автоматизация. Командните hooks управляват локално валидиране и форматиране. HTTP hooks се интегрират с външни услуги и бази данни. Hooks за подкани модифицират поведението на Claude без външни процеси.

Жизнен цикъл на Hooks и Система за събития

Официалната документация определя множество hook събития (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification и други), които се задействат по време на работния процес на Claude Code. Разбирането кога се задейства всяко от тях определя каква автоматизация става възможна.

Събития на Claude Code hooks и техния работен процес по време на типична сесия

Събитие	Кога се задейства	Може да блокира
SessionStart	Когато сесията започне или се възобнови	Не
UserPromptSubmit	Когато подадете подкана, преди Claude да я обработи	Да
PreToolUse	Преди да се изпълни извикване на инструмент	Да
PermissionRequest	Когато се появи диалог за разрешение	Да
PostToolUse	След като извикването на инструмент успее	Не
PostToolUseFailure	След като извикването на инструмент се провали	Не
Notification	Когато Claude Code изпрати известие	Не
SubmitMessage	Когато Claude изпрати съобщение до потребителя	Не
ContextCompaction	Когато прозорецът с контекст достигне лимити	Не

Възможността за блокиране е най-важна. PreToolUse hooks могат да предотвратят опасни операции, преди те да се изпълнят. Изходен код 1 блокира действието. Изходен код 0 го позволява. Изходен код 2 подтиква Claude да преосмисли.

Но почакайте. PostToolUse hooks не могат да отменят действия, тъй като инструментът вече е изпълнен. Това ограничение оформя начина, по който се структурира логиката за валидиране. Критичните проверки принадлежат на PreToolUse. Почистването и форматирането принадлежат на PostToolUse.

Разгледайте AI Tool Perks при настройка на Claude Code

Ако работите с Claude Code hooks, може би избирате и други AI инструменти около работния си процес. Get AI Perks събира стартови кредити и отстъпки за софтуер за AI и облачни инструменти на едно място. Платформата включва над 200 оферти, като условията за ползване и насоки за заявяване са налични за всяка от тях.

Търсите Claude или други AI Tool Perks?

Проверете Get AI Perks, за да:

разглеждате оферти за Claude и други AI инструменти
сравнявате условията за ползване преди кандидатстване
намирате стартиращи отстъпки за вашия пакет от инструменти

👉 Посетете Get AI Perks, за да разгледате текущите AI софтуерни perks.

Конфигурация и Структура на файлове

Hooks се дефинират във файла .claude/settings.json в рамките на проект. Схемата за конфигуриране поддържа глобални hooks и специфични за инструмента съвпадения, които филтрират кога се изпълняват hooks.

Основна структура на команден hook:

{
“hooks”: [
{
“event”: “PostToolUse”,
“command”: “prettier –write”,
“args”: [“${file}”]
}
]
}

Променливата ${file} се разширява до действителния път на файла от входа на инструмента. Според официалната документация, hooks поддържат тези разширения на променливи в полетата command и args.

Йерархия на местоположението на Hooks

Claude Code проверява множество местоположения за дефиниции на hooks, с ясен ред на приоритет:

На ниво проект: .claude/settings.json в текущото работно пространство
На ниво потребител: ~/.claude/settings.json за всички сесии
Предоставени от плъгини: Hooks, пакетирани с инсталирани плъгини

Проектните hooks презаписват потребителските hooks за едно и също събитие. Това позволява специфични за проекта правила за форматиране, като същевременно се поддържат глобални обработчици на известия.

Модели за съвпадение за Селективно Изпълнение

Системата за съвпадение филтрира hooks към специфични инструменти или условия. Без съвпадения, hooks се задействат за всяко срещане на тяхното събитие.

{
“hooks”: [
{
“event”: “PreToolUse”,
“matcher”: {
“toolName”: “edit_file”,
“pathPattern”: “src/**/*.ts”
},
“command”: “./scripts/validate-typescript.sh”
}
]
}

Полето pathPattern приема glob синтаксис. Полето toolName съвпада със вградените инструменти на Claude като edit_file, execute_command, read_file и create_directory.

Дискусиите в общността разкриват, че комбинациите от съвпадения работят с AND логика. Всички посочени съвпадения трябва да се срещнат, за да може hook-ът да се изпълни.

Командни Hooks: Интеграция със Shell Скриптове

Командните hooks изпълняват shell команди или скриптове със структуриран JSON вход. Те представляват най-често срещания тип hook за локална автоматизация.

Официалната документация посочва, че командните hooks получават JSON чрез stdin със следната структура:

{
“event”: “PreToolUse”,
“toolName”: “edit_file”,
“toolInput”: {
“path”: “src/app.ts”,
“content”: “…”
},
“sessionId”: “abc123”,
“turnId”: “turn-456”
}Скриптовете анализират този вход, за да вземат решения. Hook за валидиране с Python може да изглежда така:#!/usr/bin/env python3
import sys
import json

input_data = json.load(sys.stdin)
tool_input = input_data.get(‘toolInput’, {})
file_path = tool_input.get(‘path’, ”)

if file_path.startswith(‘protected/’):
print(“Cannot edit protected files”, file=sys.stderr)
sys.exit(1)

sys.exit(0)

Изходен код 0 позволява операцията. Изходен код 1 я блокира и показва stderr съобщението на Claude. Изходен код 2 задейства специално поведение в зависимост от събитието.

Поведение на изходен код 2

Според официалната документация за справка за hooks, изходен код 2 има значение, специфично за събитието (PreToolUse: блокира и подтиква към преосмисляне; UserPromptSubmit: предоставя контекст без блокиране; PermissionRequest: блокира разрешение):

PreToolUse: Блокира инструмента и подтиква Claude към преосмисляне със stderr съобщението като контекст
UserPromptSubmit: Предоставя stderr изхода като допълнителен контекст без блокиране
PermissionRequest: Блокира предоставянето на разрешение

Това създава среден път между твърдо блокиране и разрешаване. Claude получава обратна връзка защо действието може да е проблематично и може да коригира своя подход.

Асинхронни Командни Hooks

Флагът async: true изпълнява hooks във фонов режим, без да блокира работния процес на Claude. Това е важно за бавни операции като известия за разполагане или събиране на метрики.

{
“event”: “PostToolUse”,
“matcher”: {
“toolName”: “execute_command”
},
“command”: “./scripts/log-to-analytics.sh”,
“async”: true,
“timeout”: 30
}

Когато се задейства async hook, Claude Code стартира процеса и продължава незабавно. Полето timeout определя максималното време за изпълнение в секунди. Ако не е посочено, async hooks използват 10-минутен стандартен тайм аут.

Честно казано: async hooks не могат да блокират операции, тъй като се изпълняват, след като Claude продължи. Те работят за записване, известия и почистване - не за валидиране.

HTTP Hooks: Интеграция с Външни Услуги

HTTP hooks изпращат JSON пакети към отдалечени крайни точки и анализират отговорите за контрол на решенията. Те позволяват интеграция с услуги за валидиране, бази данни и инструменти от трети страни.

Конфигурация на базов HTTP hook:

{
“event”: “PreToolUse”,
“url”: “api.example.com/validate”,
“headers”: {
“Authorization”: “Bearer ${API_TOKEN}”
},
“timeout”: 5
}

Структурата на пакета съвпада с входа на командния hook, но пристига като HTTP POST тяло. Отговорът определя следващото действие на Claude.

Обработка на HTTP Отговори

Според официалната документация, HTTP hooks интерпретират отговорите въз основа на код на състоянието и съдържание на тялото:

Код на състоянието	Ефект	Източник на съобщение
200	Позволява операцията	Тяло на отговора (по избор)
400	Блокира операцията	Тялото на отговора се показва на Claude
500	Грешка в hook, позволява операцията	Записано, но не се показва на Claude
Друг	Позволява операцията	Грешката в hook не блокира работния процес

Тялото на отговора може да включва поле message, което Claude вижда като контекст. Това позволява на услугите за валидиране да обяснят защо операцията е била блокирана.

Интерполация на Променливи на Околна Среда

HTTP hooks поддържат синтаксис ${VAR} в url, headers и други текстови полета. Променливите се разширяват от средата, в която работи Claude Code.

Според официалната MCP документация, разширяването на променливи на околната среда включва резервен синтаксис по подразбиране: ${VAR:-default} се разширява до VAR, ако е зададена, иначе използва стойността по подразбиране.

Ограничение за сигурност: Според GitHub issue #28044, HTTP hooks могат да имат достъп само до променливи на околната среда, изрично изброени в полето за конфигуриране allowedEnvVars. Това предотвратява случайно излагане на идентификационни данни.

Prompt Hooks: Инжектиране на Контекст

Prompt hooks инжектират динамични инструкции в контекста на Claude при специфични събития. Те модифицират поведението без външни процеси или API извиквания.

{
“event”: “SessionStart”,
“prompt”: “You are working on a TypeScript project. Always use strict null checks and prefer async/await over promises.”
}

Инжектираният текст става част от системните инструкции на Claude за тази сесия. Prompt hooks могат също да използват шаблонни променливи, които се разширяват въз основа на данните от събитието.

Динамично Генериране на Подкани

Според официалната документация, prompt hooks поддържат полета command, които генерират динамични подкани:

{
“event”: “ContextCompaction”,
“type”: “prompt”,
“command”: “./scripts/generate-context-summary.sh”
}

Командата получава стандартния JSON вход чрез stdin и извежда текста на подканата към stdout. Това позволява генериране на инструкции, съобразени с контекста, въз основа на състоянието на проекта.

Hooks, Базирани на Агенти

Agent hooks посочват под-агент, който обработва събитието, вместо директно инжектиране на подкана. Под-агентът получава контекст за събитието и може да извършва многостъпкови разсъждения.

{
“event”: “PostToolUseFailure”,
“agent”: “debugger”,
“agentPrompt”: “A tool call failed. Analyze the error and suggest fixes.”
}

Именуваният под-агент трябва да бъде дефиниран в конфигурацията на проекта. Agent hooks позволяват сложна логика за вземане на решения, която простото инжектиране на подкана не може да предостави.

Практически Модели на Hooks

Дискусиите в общността и официалните примери разкриват специфични модели на автоматизация, които работят надеждно в производствена среда.

Автоматично Форматиране на Код След Редакции

Най-често срещаният модел автоматично форматира кода след като Claude редактира файлове:

{
“event”: “PostToolUse”,
“matcher”: {
“toolName”: “edit_file”,
“pathPattern”: “**/*.{js,ts,jsx,tsx}”
},
“command”: “prettier”,
“args”: [“–write”, “${toolInput.path}”]
}

Променливата ${toolInput.path} се разширява до пътя на редактирания файл. PostToolUse гарантира, че форматирането се случва след успешни редакции, но не блокира работния процес на Claude.

Блокиране на Модификации на Защитени Файлове

PreToolUse hooks налагат правила за защита на файлове:

{
“event”: “PreToolUse”,
“matcher”: {
“toolName”: “edit_file”
},
“command”: “./scripts/check-protected.sh”
}

Скриптът валидира целевия път спрямо защитени модели и излиза с код 1, за да блокира забранени редакции.

Получаване на Известия, Когато Claude Има Нужда от Вход

Според официалното ръководство за работния процес, Notification hooks могат да задействат настолни известия или да изпращат съобщения до външни услуги:

{
“event”: “Notification”,
“command”: “osascript”,
“args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””]
}

Това се задейства всеки път, когато Claude Code изпраща известие, включително когато чака потребителски вход или след завършване на задача.

Повторно Инжектиране на Контекст След Компресия

ContextCompaction hooks възстановяват важен контекст, когато прозорецът на разговора се запълни:

{
“event”: “ContextCompaction”,
“type”: “prompt”,
“command”: “cat .claude/critical-context.md”
}

Изходът от командата се инжектира обратно в контекста на Claude след като компресията премахне по-стари съобщения. Това предотвратява загубата на критични специфични за проекта инструкции.

Одит на Промените в Конфигурацията

Проследяване кога Claude модифицира конфигурационни файлове:

{
“event”: “PostToolUse”,
“matcher”: {
“toolName”: “edit_file”,
“pathPattern”: “**/{package.json,.env,*.config.*}”
},
“command”: “git”,
“args”: [“add”, “${toolInput.path}”],
“async”: true
}

Асинхронното изпълнение предотвратява блокирането на Claude, докато git операциите приключат. Това създава одитна пътека на промените в конфигурацията без ръчно добавяне.

JSON Изход и Контрол на Решенията

Командните hooks могат да генерират структуриран JSON, за да предоставят подробна обратна връзка отвъд прости изходни кодове. Според официалната справка, JSON изходът позволява многополетни отговори, които Claude интерпретира за вземане на решения.

{
“allowed”: false,
“message”: “This file is protected by team policy”,
“suggestion”: “Create a new file in src/features/ instead”
}

Полето allowed контролира дали операцията продължава. Съобщението се показва на Claude като контекст. Полето suggestion предоставя алтернативни подходи.

За да могат hooks да генерират JSON, те трябва:

Да записват валиден JSON към stdout
Да излизат с код 0 (за разрешени) или 1 (за блокирани)
Да включват поне полето allowed като булева стойност

Claude Code анализира JSON и го използва за подобряване на цикъла на обратна връзка. Изходните кодове все още определят основното решение, но JSON предоставя по-богат контекст.

Справка за Полета на Входни Данни на Hooks

Всички hooks получават JSON обект чрез stdin с общи полета плюс данни, специфични за събитието. Разбирането на пълната схема позволява по-сложна логика на hooks.

Схема на JSON входните данни на Hook, показваща общи полета и разширения, специфични за събития

Общи Полета за Входни Данни

Всеки hook получава тези основни полета:

event: Името на hook събитието (напр. "PreToolUse")
sessionId: Уникален идентификатор за текущата Claude сесия
turnId: Идентификатор за текущия ход на разговора
timestamp: ISO 8601 времеви печат, когато събитието се е задействало

Полета за Инструмент Събития

Събитията PreToolUse, PostToolUse и PostToolUseFailure включват:

toolName: Име на инструмента, който се извиква (edit_file, execute_command и т.н.)
toolInput: Обект, съдържащ параметрите за вход на инструмента
toolResponse: Изходни данни на инструмента (само PostToolUse)
error: Детайли за грешката, включително съобщение и код (само PostToolUseFailure)

Структурата на toolInput варира в зависимост от инструмента. За edit_file той съдържа path и content. За execute_command той съдържа command и args.

Полета за Събития за Разрешение

Събитията PermissionRequest включват:

permissionType: Типът на исканото разрешение (file_write, command_execute и т.н.)
requestedAction: Конкретното действие, изискващо разрешение
resourcePath: Пътят на файла или идентификаторът на ресурса, който е засегнат

MCP Инструмент Hooks

Според официалната справка за hooks, hooks могат да съвпадат с инструменти от Model Context Protocol (MCP), използвайки полето за съвпадение mcpTool. Това позволява изпълнението на hooks, когато Claude използва външни инструменти, предоставени от MCP сървъри.

{
“event”: “PreToolUse”,
“matcher”: {
“mcpTool”: “database/query”
},
“command”: “./scripts/validate-sql.sh”
}

Стойността mcpTool съвпада с името на инструмента във формат server-name/tool-name. Това позволява логика за валидиране за SQL заявки, API извиквания или други външни операции.

Заявките за функции в GitHub показват нарастващ интерес към по-дълбока MCP интеграция, включително hooks, които могат да инспектират известия от MCP сървъри и да отговарят на външни събития.

Съображения за Сигурност

Hooks се изпълняват със същите права като Claude Code. Това създава последствия за сигурността за многопотребителски среди и споделени конфигурации.

Sandbox за Изпълнение на Команди

Според GitHub issue #28044, HTTP hooks преминават през sandbox прокси, което ограничава мрежовия достъп и филтрира променливите на околната среда. Командните hooks нямат такива ограничения - те се изпълняват с пълен достъп до shell.

Документацията препоръчва следните практики:

Никога не съхранявайте идентификационни данни в команди на hooks
Използвайте променливи на околната среда за чувствителни данни
Валидирайте всички входни данни от разширения ${…}
Прилагайте ограничения за тайм аут за външни услуги
Използвайте async hooks за некритични операции, за да предотвратите блокиране при грешки

Изолация на Изпълнението на Hooks

Hooks на ниво потребител в ~/.claude/settings.json се прилагат за всички проекти. Това създава рискове при работа между различни граници на доверие. Проектните hooks презаписват потребителските hooks, но не могат напълно да ги деактивират.

Менюто /hooks в Claude Code показва всички активни hooks за текущата сесия. Прегледът на този списък преди работа по чувствителни проекти помага за идентифициране на потенциални проблеми със сигурността.

Отстраняване на Грешки и Диагностика

Грешките в hooks не винаги се показват ясно в разговора на Claude. Официалната документация предоставя няколко подхода за отстраняване на грешки.

Лог за Изпълнение на Hooks

Claude Code записва изпълнението на hooks в дебъг изхода на сесията. Според ръководството за отстраняване на проблеми, активирането на дебъг логване разкрива:

Кои hooks са съвпаднали за всяко събитие
JSON входните данни, изпратени към всеки hook
Stdout и stderr изхода от hook процесите
Изходни кодове и време на изпълнение
HTTP кодове и тела на отговори за HTTP hooks

Активирайте дебъг логване, като зададете CLAUDE_DEBUG=1 в околната среда преди стартиране на Claude Code.

Независимо Тестване на Hooks

Командните hooks могат да бъдат тествани извън Claude Code чрез ръчно конструиране на JSON вход:

echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh

Това валидира логиката на hook, без да задейства действителни Claude операции. Изходният код и stdout/stderr изходът трябва да съответстват на очакваното поведение.

Чести Грешки в Hooks

Дискусиите в общността идентифицират следните чести проблеми:

Грешки при тайм аут: Стандартният 10-минутен тайм аут е твърде кратък за бавни операции - увеличете с полето timeout
Грешки при разширяване на пътя: Променливи като ${file} са недефинирани за събития, които не включват контекст на файл
Грешки при разрешение: Hook скриптовете нямат права за изпълнение - изпълнете chmod +x script.sh
Грешки при парсване на JSON: Неправилен JSON изход от hooks - валидирайте с jq преди връщане
Недостъпни променливи на околната среда: Променливи, които не са предадени на hook процеса - проверете средата на Claude Code

Въздействие на Hooks върху Производителността

Синхронните hooks блокират работния процес на Claude до завършване. Стандартният 10-минутен тайм аут предотвратява безкрайно блокиране, но дори кратки закъснения се натрупват при множество операции.

Практикуващите съобщават, че прости hooks за валидиране имат незначително въздействие върху производителността. Hooks за форматиране на файлове причиняват забележимо, но приемливо въздействие върху производителността. Извикванията на външни API могат да създадат триене в работния процес. Операциите с тежки изчисления се възползват от асинхронно изпълнение.

Групиране на Hooks

Няколко hooks могат да съвпадат с едно и също събитие. Според справочната документация, hooks се изпълняват последователно по реда на дефиниция. Ако някой hook блокира операцията, останалите hooks не се изпълняват.

Това е важно за производителността. Пет синхронни hooks по 200ms всеки добавят една секунда на събитие. Комбинирането на свързани валидации в един hook намалява режийните разходи.

Разширени Модели

Отвъд основната автоматизация, hooks позволяват сложна персонализация на работния процес.

Състояния на Hook Вериги

Hooks могат да поддържат състояние между изпълненията, като използват файлове или бази данни. Hook PostToolUse може да записва успешни операции, които hook PreToolUse по-късно валидира срещу:

#!/bin/bash
# Record successful edits
echo “${toolInput.path}” >> .claude/edit-history.txt

Свързан PreToolUse hook може да проверява тази история, за да предотврати повторни операции или да налага ограничения за поредност.

Условно Активиране на Hooks

Променливите на околната среда контролират поведението на hooks по време на изпълнение. Задаването на CLAUDE_SKIP_HOOKS=1 деактивира hooks за спешни ситуации.

Самите hooks могат да проверяват флагове на околната среда:

#!/bin/bash
if [ “$STRICT_MODE” = “1” ]; then
# Apply strict validation
exit 1
fi
exit 0

Това позволява поведение в режим на разработка спрямо режим на производство без промени в конфигурацията.

Многостепенно Валидиране

PreToolUse hooks могат да приложат многостепенно валидиране, където изходен код 2 позволява на Claude да продължи с предупреждения:

Твърди неуспехи (изходен код 1): Блокиране на опасни операции
Меки предупреждения (изходен код 2): Уведомяване на Claude да преосмисли
Преминаване с контекст (изходен код 0 + JSON): Предоставяне на допълнителна информация

Това създава спектър на валидиране, по-нюансиран от двоично разрешаване/отказ.

Интеграция с CI/CD

Според официалната документация за интеграция на платформата, Claude Code работи в CI/CD среди за автоматизиран преглед на код и триаж на проблеми. Hooks разширяват тази автоматизация.

GitHub Actions работни процеси могат да дефинират hooks, които налагат екипни политики по време на автоматизирани сесии:

-- name: Run Claude Code with strict hooks
env:
STRICT_MODE: 1
run: |
claude “Review this PR and suggest improvements”

Флагът STRICT_MODE активира условната логика за валидиране в hook скриптовете. Това гарантира, че автоматизираните сесии следват по-строги правила от интерактивната разработка.

Генериране на Одитна Пътека

PostToolUse hooks в CI среди създават подробни одитни логове на всички Claude операции:

{
“event”: “PostToolUse”,
“command”: “./scripts/log-to-database.sh”,
“async”: true
}

Фоновото записване не влияе на производителността, но предоставя пълна история на операциите за съответствие и отстраняване на грешки.

Менюто /hooks

Claude Code предоставя команда /hooks, която показва всички активни hooks за текущата сесия. Според официалната документация, това меню показва:

Тип на hook събитието
Модели за съвпадение
Команда или URL крайна точка
Дали hook-ът се изпълнява асинхронно
Източник на конфигурация (проект, потребител или плъгин)

Изборът на hook показва неговата пълна конфигурация и позволява временно деактивиране за текущата сесия.

Деактивиране или Премахване на Hooks

Hooks могат да бъдат деактивирани, без да се премахва конфигурацията, чрез добавяне на "enabled": false към дефиницията на hook. Това запазва конфигурацията, като същевременно предотвратява изпълнението.

За да премахнете hook трайно, изтрийте неговия запис от съответния settings.json файл. Промените влизат в сила при следващото рестартиране на сесията или при изпълнение на /reload.

Hooks в Skills и Агенти

Според официалната документация, hooks, дефинирани в конфигурации на skills или под-агенти, се прилагат само когато този skill или агент се изпълнява. Това позволява специализирана автоматизация за специфични работни процеси.

Дебъгващ под-агент може да включва hooks, които записват всички извиквания на инструменти:

{
“name”: “debugger”,
“hooks”: [
{
“event”: “PostToolUse”,
“command”: “./scripts/log-debug.sh”,
“async”: true
}
]
}

Тези hooks се задействат само по време на сесии на debugger агент, а не по време на нормална работа на Claude Code.

Отнасяне към Скриптове по Път

Командите на Hooks поддържат както относителни, така и абсолютни пътища. Относителните пътища се разрешават от корена на проекта, където работи Claude Code.

Най-добри практики от дискусиите в общността:

Съхранявайте hook скриптове в директория .claude/hooks/
Използвайте описателни имена: validate-typescript.sh вместо hook1.sh
Направете скриптовете изпълними: chmod +x .claude/hooks/*.sh
Включете shebang ред: #!/usr/bin/env bash или #!/usr/bin/env python3
Добавете обработка на грешки с set -e в bash скриптове

Бъдещи Възможности на Hooks

Заявките за функции в GitHub разкриват планирани и поискани подобрения на hooks:

Inline скрипт hooks: Дефиниране на hook логика директно в settings.json без външни файлове
MCP инструмент интеграция: Извикване на MCP сървър инструменти от hooks вместо shell команди
Мулти-агентно сътрудничество: Hooks, които координират между Claude инстанции на различни машини
Разширено типизиране: TypeScript типови дефиниции за схеми на входни/изходни данни на hooks

Според GitHub issue #4274, заявката за интегрирани типове hooks (MCP инструмент, inline скрипт, API извикване) има за цел да опрости конфигурацията и да подобри потребителското изживяване на разработчиците.

Често Задавани Въпроси

Могат ли hooks да предотвратят изпълнението на опасни команди от Claude?

Да. PreToolUse hooks могат да блокират всяко изпълнение на инструмент, като излязат с код 1. Това включва редакции на файлове, изпълнение на команди и MCP извиквания на инструменти. Hook получава пълните входни данни на инструмента и може да валидира спрямо всякакви критерии, преди да позволи операцията.

Как да отстранявам грешки в hook, който не работи?

Активирайте дебъг логване с CLAUDE_DEBUG=1 преди стартиране на Claude Code. Проверете логoвете на сесията за детайли за изпълнението на hook, включително кои hooks са съвпаднали, JSON входните данни, изпратени stdout/stderr изход и изходни кодове. Тествайте hooks независимо, като предавате примерни JSON към hook скрипта.

Работят ли hooks с всички платформи на Claude Code?

Hooks работят в CLI, десктоп приложението и VS Code разширението. Според официалната документация, hooks се изпълняват навсякъде, където Claude Code работи с достъп до файловата система. Браузърни Claude и мобилни приложения не поддържат hooks поради ограниченията на sandbox.

Могат ли hooks да модифицират отговорите или поведението на Claude?

Prompt hooks инжектират инструкции, които влияят на поведението на Claude. Agent hooks делегират обработката на събития на специализирани под-агенти. Въпреки това, hooks не могат директно да модифицират генерирания текст или процес на разсъждение на Claude - те работят чрез предоставяне на контекст и блокиране на операции.

Каква е разликата между async и sync hooks?

Синхронните hooks блокират работния процес на Claude до завършване или изтичане на тайм аут. Асинхронните hooks работят във фонов режим, без да блокират. Sync hooks могат да предотвратят операции чрез изходни кодове. Async hooks не могат да блокират, тъй като Claude продължава преди hook-ът да приключи. Използвайте async за записване и известия, sync за валидиране.

Как да споделям hooks в екип?

Качвайте файла .claude/settings.json в система за контрол на версиите. Проектните hooks се прилагат за всички членове на екипа, които клонират хранилището. За политики на цялата организация, екипите могат да поддържат общ файл с настройки на ниво потребител, който членовете копират в ~/.claude/settings.json.

Могат ли HTTP hooks да извикват вътрешни API зад защитни стени?

Да, ако Claude Code работи в среда с мрежов достъп до тези API. HTTP hooks правят стандартни POST заявки от машината, която изпълнява Claude Code. Корпоративните защитни стени и VPN се прилагат нормално. Sandbox проксито, споменато в документацията, контролира излагането на променливи на околната среда, а не мрежовото маршрутизиране.

Увеличават ли hooks използването на токени на Claude Code?

Prompt hooks инжектират текст в контекста на Claude, което консумира токени. Командните и HTTP hooks не влияят пряко на използването на токени, но техният изход (съобщения за грешки, предложения) става част от контекста на разговора. Изходен код 2 с обяснителни съобщения добавя повече контекст от изходен код 1 с просто блокиране.

Заключение

Claude Code hooks превръщат AI асистента от мощен инструмент в напълно автоматизирана платформа за разработка. Системата за събития предоставя точки за прихващане през целия работен процес на Claude - от инициализацията на сесията до компресията на контекста.

Командните hooks управляват локално валидиране и форматиране. HTTP hooks интегрират външни услуги и бази данни. Prompt hooks модифицират поведението чрез инжектиране на контекст. Заедно те позволяват модели на автоматизация, които налагат екипни политики, поддържат качеството на кода и се интегрират със съществуващата инфраструктура за разработка.

Системата за съвпадение филтрира hooks към специфични инструменти и файлови модели. Изходните кодове и JSON изходът контролират потока на решения. Асинхронното изпълнение предотвратява блокиране при бавни операции. Пълната схема на конфигуриране поддържа всичко - от просто автоматично форматиране до сложно многостепенно валидиране.

Започнете с базови PostToolUse hooks за форматиране на код. Добавете PreToolUse валидиране, когато се появят политики. Експериментирайте с prompt hooks за модификация на поведението. Изградете HTTP интеграции за екипно налагане.

Проверете официалната документация на Claude Code за пълната справка за hooks и актуализирана схема на конфигуриране, тъй като се доставят нови възможности.