Արագ ամփոփում. Claude Code hook-երը ավտոմատացման սկրիպտներ են, որոնք կատարվում են AI կոդավորման նստաշրջանների կյանքի ցիկլի որոշակի կետերում, թույլ տալով մշակողներին կատարել մաքսային հրամաններ, հաստատել գործողությունները, ձևաչափել կոդը, ուղարկել ծանուցումներ և կիրառել նախագծի կանոնները։ Այս hook-երը ինտեգրվում են Claude-ի աշխատանքային հոսքին այնպիսի իրադարձությունների միջոցով, ինչպիսիք են SessionStart, PreToolUse և PostToolUse, աջակցելով հրամանային, HTTP-ի վրա հիմնված և prompt-ի վրա հիմնված կատարման ձևերին՝ կազմաձևվող ժամկետներով և ելքային կոդի վարքագծով։
Claude Code-ի hook համակարգը AI կոդավորման օգնականը վերածում է օգտակար գործիքից ամբողջովին ավտոմատացված մշակման միջավայրի։ Մշակողների մեծ մասը չի գիտակցում hook-երի միջոցով հասանելի վերահսկողության չափը։
Ահա գլխավորը՝ hook-երը ոչ միայն ֆայլերի փոփոխություններից հետո սկրիպտներ գործարկելու մասին են։ Նրանք տրամադրում են միջամտության կետեր Claude-ի ամբողջ որոշում կայացնելու գործընթացում։ Մինչև այն կկատարի հրամանը։ Գործիքի կանչը ձախողվելուց հետո։ Երբ նրան թույլտվություն է հարկավոր։ Նույնիսկ օգտվողի prompts-ը մշակելուց առաջ։
Այս ուղեցույցը ընդգրկում է այն ամենը, ինչը տրամադրում է պաշտոնական փաստաթղթերը, գումարած գործնական ձևեր, որոնք համայնքի քննարկումները բացահայտում են, որոնք իրականում աշխատում են արտադրական միջավայրերում։
Ի՞նչ են իրականում անում Claude Code Hook-երը
Ըստ Claude Code-ի պաշտոնական փաստաթղթերի, hook-երը օգտվողի կողմից սահմանված shell հրամաններ են, HTTP վերջակետեր կամ prompt ներարկումներ, որոնք կատարվում են Claude Code-ի կյանքի ցիկլի որոշակի կետերում։ Նրանք ստանում են կառուցվածքային JSON մուտք stdin-ի միջոցով և վերահսկում աշխատանքային հոսքը ելքային կոդերի կամ HTTP պատասխանների միջոցով։
Ավտոմատացումն ավելի խորն է, քան մեծ մասը ուղեցույցների ենթադրում է։ Hook-երը կարող են ամբողջովին արգելափակել գործիքի կատարումը, լրացուցիչ կոնտեքստ ներարկել Claude-ի մտահանգումներում, գործարկել արտաքին ծառայություններ և կիրառել հաստատման կանոններ, որոնց Claude-ը պետք է հնազանդվի։
Կան երեք հիմնական hook տեսակ.
- Հրամանային hook-եր. Shell սկրիպտներ, որոնք հաղորդակցվում են stdout, stderr և ելքային կոդերի միջոցով։
- HTTP hook-եր. Հեռավոր վերջակետեր, որոնք ստանում են POST հարցումներ և վերադարձնում JSON պատասխաններ։
- Prompt hook-եր. Դինամիկ հրահանգներ, որոնք ներարկվում են Claude-ի կոնտեքստին որոշակի իրադարձություններում։
Յուրաքանչյուր տեսակ ծառայում է տարբեր ավտոմատացման ձևեր։ Հրամանային hook-երը մշակում են տեղական հաստատում և ձևավորում։ HTTP hook-երը ինտեգրվում են արտաքին ծառայությունների և բազաների հետ։ Prompt hook-երը փոփոխում են Claude-ի վարքագիծը արտաքին գործընթացների միջոցով։
Hook Կյանքի Ցիկլ և Իրադարձությունների Համակարգ
Պաշտոնական փաստաթղթերը սահմանում են բազմաթիվ hook իրադարձություններ (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification և այլն), որոնք կատարվում են Claude Code-ի կատարման հոսքի ընթացքում։ Յուրաքանչյուրը երբ է կատարվում հասկանալը որոշում է, թե որ ավտոմատացումն է հնարավոր։
| Իրադարձություն | Ե՞րբ է կատարվում | Կարող է արգելափակել |
|---|---|---|
| SessionStart | Երբ նստաշրջանը սկսվում կամ վերսկսվում է | Ոչ |
| UserPromptSubmit | Երբ դուք ներկայացնում եք prompt, մինչև Claude-ը մշակում է այն | Այո |
| PreToolUse | Մինչև գործիքի կանչը կատարվի | Այո |
| PermissionRequest | Երբ հայտնվում է թույլտվության երկխոսություն | Այո |
| PostToolUse | Գործիքի կանչը հաջողվելուց հետո | Ոչ |
| PostToolUseFailure | Գործիքի կանչը ձախողվելուց հետո | Ոչ |
| Notification | Երբ Claude Code-ը ծանուցում է ուղարկում | Ոչ |
| SubmitMessage | Երբ Claude-ը հաղորդագրություն է ներկայացնում օգտատիրոջը | Ոչ |
| ContextCompaction | Երբ կոնտեքստային պատուհանը մոտենում է սահմաններին | Ոչ |
Արգելափակման հնարավորությունը ամենակարևորն է։ PreToolUse hook-երը կարող են կանխել վտանգավոր գործողությունները մինչև դրանց կատարումը։ Exit code 1-ը արգելափակում է գործողությունը։ Exit code 0-ը թույլատրում է այն։ Exit code 2-ը դրդում է Claude-ին վերանայել։
Բայց սպասեք։ PostToolUse hook-երը չեն կարող չեղարկել գործողությունները, քանի որ գործիքն արդեն կատարվել է։ Այս սահմանափակումը ձևավորում է, թե ինչպես է կառուցվում հաստատման տրամաբանությունը։ Կրիտիկական ստուգումները պատկանում են PreToolUse-ին։ Մաքրումը և ձևավորումը պատկանում են PostToolUse-ին։
Թերթեք AI Գործիքային Perks-երը Claude Code-ը Կարգավորելիս
Եթե դուք աշխատում եք Claude Code hook-երի հետ, դուք նաև կարող եք ընտրել այլ AI գործիքներ ձեր աշխատանքային հոսքի շուրջ։ Get AI Perks-ը հավաքում է ստարտափ վարկեր և ծրագրային զեղչեր AI և cloud գործիքների համար մեկ տեղում։ Պլատֆորմը ներառում է 200+ առաջարկներ, յուրաքանչյուրի համար perks պայմաններով և պահանջի ուղեցույցներով։
Փնտրում եք Claude կամ Այլ AI Գործիքային Perks-եր?
Ստուգեք Get AI Perks-ը՝
- թերթել Claude-ը և այլ AI գործիքային առաջարկները
- համեմատել perks պայմանները դիմելուց առաջ
- գտնել ստարտափ զեղչեր ձեր գործիքային փաթեթում
👉 Այցելեք Get AI Perks-ը՝ ներկայիս AI ծրագրային perks-երը ուսումնասիրելու համար։
Կարգաւորում և Ֆայլային Կառուցվածք
Hook-երը սահմանվում են .claude/settings.json ֆայլում՝ նախագծի ներսում։ Կարգաւորման սխեման աջակցում է գլոբալ hook-երին և գործիքին-հատուկ մատչերներին, որոնք զտում են, երբ hook-երն են կատարվում։
Հիմնական հրամանային hook կառուցվածք:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
${file} փոփոխականը ընդլայնվում է գործիքային մուտքի իրական ֆայլի ուղուն։ Ըստ պաշտոնական փաստաթղթերի, hook-երը աջակցում են այս փոփոխական ընդլայնումները հրամանային և args դաշտերում։
Hook Դիրքի Հիերարխիա
Claude Code-ը ստուգում է բազմաթիվ վայրեր hook սահմանումների համար, հստակ առաջնահերթության կարգով:
- Նախագծային մակարդակ. .claude/settings.json ընթացիկ աշխատատեղում
- Օգտատիրոջ մակարդակ. ~/.claude/settings.json բոլոր նստաշրջանների համար
- Plugin-ի տրամադրած. Hook-եր՝ տեղադրված plugin-ների հետ փաթեթավորված
Նախագծային hook-երը գերակշռում են օգտատիրոջ hook-երի վրա նույն իրադարձության համար։ Սա թույլ է տալիս նախագծին-հատուկ ձևավորման կանոններ, պահպանելով գլոբալ ծանուցման բաժանորդներին:
Մատչերի Ձևաչափեր Ընտրովի Կատարման համար
Մատչեր համակարգը զտում է hook-երը դեպի որոշակի գործիքներ կամ պայմաններ։ Առանց մատչերների, hook-երը կատարվում են իրենց իրադարձության յուրաքանչյուր դեպքի համար։
| { “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-ը կատարվի։
Հրամանային Hook-եր: Shell Սկրիպտների Ինտեգրում
Հրամանային hook-երը կատարում են shell հրամաններ կամ սկրիպտներ՝ կառուցվածքային JSON մուտքով։ Նրանք ներկայացնում են ամենատարածված hook տեսակը տեղական ավտոմատացման համար։
Պաշտոնական փաստաթղթերը նշում են, որ հրամանային hook-երը ստանում են JSON stdin-ի միջոցով այս կառուցվածքով:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Scripts parse this input to make decisions. A Python validation hook might look like:#!/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) |
Exit code 0-ը թույլատրում է գործողությունը։ Exit code 1-ը արգելափակում է այն և stderr հաղորդագրությունը ցույց է տալիս Claude-ին։ Exit code 2-ը գործարկում է հատուկ վարքագիծ՝ կախված իրադարձությունից։
Exit Code 2 Վարքագիծ
Ըստ պաշտոնական hooks հղման փաստաթղթերի, exit code 2-ը ունի իրադարձություն-հատուկ իմաստ (PreToolUse: արգելափակում է և խնդրում վերանայել; UserPromptSubmit: տրամադրում է կոնտեքստ առանց արգելափակման; PermissionRequest: արգելափակում է թույլտվությունը):
- PreToolUse. Արգելափակում է գործիքը և խնդրում Claude-ին վերանայել stderr հաղորդագրությունը՝ որպես կոնտեքստ։
- UserPromptSubmit. Դիտարկում է stderr ելքը որպես լրացուցիչ կոնտեքստ՝ առանց արգելափակման։
- PermissionRequest. Արգելափակում է թույլտվությունը։
Սա ստեղծում է միջին գոտի կոշտ արգելափակման և թույլատրման միջև։ Claude-ը ստանում է հետադարձ կապ, թե ինչու գործողությունը կարող է խնդրահարույց լինել, և կարող է փոխել իր մոտեցումը։
Ասինխրոն Հրամանային Hook-եր
async: true դրոշը գործարկում է hook-երը ֆոնային ռեժիմում՝ չարգելափակելով Claude-ի աշխատանքային հոսքը։ Սա կարևոր է դանդաղ գործողությունների համար, ինչպիսիք են deployment ծանուցումները կամ մետրիկայի հավաքումը։
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Երբ async hook-ը կատարվում է, Claude Code-ը գործարկում է գործընթացը և անմիջապես շարունակում։ timeout դաշտը սահմանում է առավելագույն կատարման ժամանակը վայրկյաններով։ Եթե չի նշված, async hook-երը օգտագործում են 10-րոպեանոց լռելյայն ժամկետ։
Իրական խոսք. async hook-երը չեն կարող արգելափակել գործողությունները, քանի որ դրանք կատարվում են այն բանից հետո, երբ Claude-ը շարունակում է։ Նրանք աշխատում են logging, ծանուցումների և մաքրման համար՝ ոչ թե հաստատման։
HTTP Hook-եր: Արտաքին Ծառայության Ինտեգրում
HTTP hook-երը POST JSON payload-ներ են ուղարկում հեռավոր վերջակետերին և վերլուծում պատասխանները՝ որոշում կայացնելու համար։ Նրանք հնարավորություն են տալիս ինտեգրվել հաստատման ծառայությունների, բազաների և երրորդ կողմի գործիքների հետ։
Հիմնական HTTP hook-ի կարգաւորում:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Payload-ի կառուցվածքը համընկնում է հրամանային hook-ի մուտքի հետ, բայց ժամանում է որպես HTTP POST մարմին։ Պատասխանը որոշում է Claude-ի հաջորդ գործողությունը։
HTTP Պատասխանի Մշակում
Ըստ պաշտոնական փաստաթղթերի, HTTP hook-երը մեկնաբանում են պատասխանները՝ ելնելով կարգավիճակի կոդից և մարմնի բովանդակությունից:
| Կարգավիճակի Կոդ | Ազդեցություն | Հաղորդագրության Աղբյուր |
|---|---|---|
| 200 | Թույլատրել գործողությունը | Պատասխանի մարմին (ըստ ցանկության) |
| 400 | Արգելափակել գործողությունը | Պատասխանի մարմինը ցուցադրվում է Claude-ին |
| 500 | Hook-ի սխալ, թույլատրել գործողությունը | Գրանցված է, բայց չի ցուցադրվում Claude-ին |
| Այլ | Թույլատրել գործողությունը | Hook-ի ձախողումը չի արգելափակում աշխատանքային հոսքը |
Պատասխանի մարմինը կարող է ներառել message դաշտ, որը Claude-ը տեսնում է որպես կոնտեքստ։ Սա թույլ է տալիս հաստատման ծառայություններին բացատրել, թե ինչու է գործողությունը արգելափակվել։
Շրջակա Միջավայրի Փոփոխականների Փոխարինում
HTTP hook-երը աջակցում են ${VAR} սինտաքսը url, headers և այլ string դաշտերում։ Փոփոխականները ընդլայնվում են Claude Code-ի կատարման միջավայրից։
Ըստ MCP-ի պաշտոնական փաստաթղթերի, շրջակա միջավայրի փոփոխականների ընդլայնումը ներառում է լռելյայն fallback սինտաքս. ${VAR:-default} ընդլայնվում է VAR-ով, եթե սահմանված է, հակառակ դեպքում օգտագործում է լռելյայն արժեքը։
Անվտանգության սահմանափակում. Ըստ GitHub issue #28044-ի, HTTP hook-երը կարող են մուտք գործել միայն այն շրջակա միջավայրի փոփոխականներին, որոնք հստակ նշված են allowedEnvVars կարգաւորման դաշտում։ Սա կանխում է պատահական հավաստագրերի բացահայտումը։
Prompt Hook-եր: Կոնտեքստի Ներարկում
Prompt hook-երը ներարկում են դինամիկ հրահանգներ Claude-ի կոնտեքստին որոշակի իրադարձություններում։ Նրանք փոփոխում են վարքագիծը՝ առանց արտաքին գործընթացների կամ API կանչերի։
| { “event”: “SessionStart”, “prompt”: “Դուք աշխատում եք TypeScript նախագծի վրա։ Միշտ օգտագործեք strict null checks և նախընտրեք async/await-ը promises-ի վրա։” } |
Ներարկված տեքստը դառնում է Claude-ի համակարգային հրահանգների մասը այդ նստաշրջանի համար։ Prompt hook-երը կարող են նաև օգտագործել template փոփոխականներ, որոնք ընդլայնվում են՝ ելնելով իրադարձության տվյալներից։
Դինամիկ Prompt Ստեղծում
Ըստ պաշտոնական փաստաթղթերի, prompt hook-երը աջակցում են հրամանային դաշտերին, որոնք ստեղծում են դինամիկ prompts:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Հրամանը ստանում է ստանդարտ JSON մուտք stdin-ի միջոցով և արտահանում է prompt տեքստը stdout-ին։ Սա թույլ է տալիս կոնտեքստ-գիտակցված հրահանգների ստեղծում, որոնք հիմնված են նախագծի վիճակի վրա։
Գործակալ-Հիմնված Hook-եր
Գործակալ hook-երը նշում են ենթագործակալ, որը մշակում է իրադարձությունը՝ ուղղակի prompt ներարկման փոխարեն։ Ենթագործակալը ստանում է կոնտեքստ իրադարձության մասին և կարող է կատարել բազմափուլ մտահանգում։
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Գործիքի կանչը ձախողվեց։ Վերլուծեք սխալը և առաջարկեք լուծումներ։” } |
Անունով ենթագործակալը պետք է սահմանվի նախագծի կարգաւորման մեջ։ Գործակալ hook-երը թույլ են տալիս բարդ որոշում կայացնելու տրամաբանություն, որը պարզ prompt ներարկումը չի կարող ապահովել։
Գործնական Hook Ձևեր
Համայնքային քննարկումները և պաշտոնական օրինակները բացահայտում են կոնկրետ ավտոմատացման ձևեր, որոնք հուսալիորեն աշխատում են արտադրության մեջ:
Ավտո-Ձևավորել Կոդը Փոփոխություններից Հետո
Ամենատարածված ձևը ավտոմատ կերպով ձևավորում է կոդը, երբ Claude-ը փոփոխում է ֆայլերը:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
${toolInput.path} փոփոխականը ընդլայնվում է փոփոխված ֆայլի ուղուց։ PostToolUse-ը ապահովում է, որ ձևավորումը կատարվի հաջողված փոփոխություններից հետո, բայց չի արգելափակում Claude-ի աշխատանքային հոսքը։
Արգելափակել Պահպանված Ֆայլերի Փոփոխությունները
PreToolUse hook-երը կիրառում են ֆայլերի պահպանման կանոնները:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Սկրիպտը հաստատում է թիրախային ուղին պաշտպանված ձևերի դեմ և ավարտվում է 1 կոդով՝ արգելելով արգելված փոփոխությունները:
Ստանալ Ծանուցումներ, Երբ Claude-ին Մուտք է Հարկավոր
Ըստ պաշտոնական աշխատանքային հոսքի ուղեցույցի, Notification hook-երը կարող են գործարկել desktop ահազանգեր կամ հաղորդագրություններ ուղարկել արտաքին ծառայություններին:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Սա կատարվում է ամեն անգամ, երբ Claude Code-ը ծանուցում է ուղարկում, ներառյալ, երբ սպասում է օգտատիրոջ մուտքին կամ առաջադրանքի ավարտից հետո։
Վերա-Ներարկել Կոնտեքստը Կոմպակտացումից Հետո
ContextCompaction hook-երը վերականգնում են կարևոր կոնտեքստը, երբ զրույցի պատուհանը լցվում է:
| { “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 Արտահանում և Որոշումների Վերահսկում
Հրամանային hook-երը կարող են արտահանել կառուցվածքային JSON՝ ավելի մանրամասն հետադարձ կապ տրամադրելու համար, պարզ ելքային կոդերից դուրս։ Ըստ պաշտոնական հղման, JSON արտահանումը թույլ է տալիս բազմադաշտ պատասխաններ, որոնք Claude-ը մեկնաբանում է՝ որոշումներ կայացնելու համար։
| { “allowed”: false, “message”: “Այս ֆայլը պաշտպանված է թիմի քաղաքականությամբ”, “suggestion”: “Ստեղծեք նոր ֆայլ src/features/ դաշտում։” } |
allowed դաշտը վերահսկում է, արդյոք գործողությունը կշարունակվի։ Հաղորդագրությունը հայտնվում է Claude-ին՝ որպես կոնտեքստ։ suggestion դաշտը տրամադրում է այլընտրանքային մոտեցումներ։
Հուկերի համար JSON արտահանելու համար, դրանք պետք է.
- Գրել վավեր JSON stdout-ին
- Ավարտվել 0 (թույլատրվածի համար) կամ 1 (արգելվածի համար) կոդով
- Ներառել առնվազն allowed բուլյան դաշտ
Claude Code-ը վերլուծում է JSON-ը և օգտագործում այն՝ հետադարձ կապի հանգույցը հարստացնելու համար։ Exit կոդերը դեռ որոշում են հիմնական որոշումը, բայց JSON-ը ապահովում է ավելի հարուստ կոնտեքստ։
Hook Մուտքային Դաշտերի Հղում
Բոլոր hook-երը ստանում են JSON օբյեկտ stdin-ի միջոցով՝ ընդհանուր դաշտերով, գումարած իրադարձություն-հատուկ տվյալներ։ Ամբողջական սխեման հասկանալը թույլ է տալիս ավելի բարդ 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 Գործիքային Hook-եր
Ըստ պաշտոնական hooks հղման, hook-երը կարող են համընկնել Model Context Protocol (MCP) գործիքների հետ՝ օգտագործելով mcpTool մատչեր դաշտը։ Սա հնարավորություն է տալիս hook-երի կատարմանը, երբ Claude-ը օգտագործում է MCP սերվերների կողմից տրամադրվող արտաքին գործիքներ:
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
mcpTool արժեքը համընկնում է գործիքի անվան հետ `server-name/tool-name` ձևաչափով։ Սա թույլ է տալիս հաստատման տրամաբանություն database queries, API calls, կամ այլ արտաքին գործողությունների համար։
GitHub-ի հատկությունների խնդրանքները ցույց են տալիս MCP ինտեգրման աճող հետաքրքրություն, ներառյալ hook-երը, որոնք կարող են ստուգել MCP սերվերի ծանուցումները և արձագանքել արտաքին իրադարձություններին:
Անվտանգության )').' ');
Hook-երը կատարվում են Claude Code-ի նույն թույլտվություններով։ Սա ստեղծում է անվտանգության հետևանքներ բազմաօգտատեր միջավայրերի և համօգտագործված կարգաւորումների համար:
Հրամանի Կատարման Sandbox
Ըստ GitHub issue #28044-ի, HTTP hook-երը անցնում են sandbox proxy-ի միջով, որը սահմանափակում է ցանցային մուտքը և զտում է շրջակա միջավայրի փոփոխականները։ Հրամանային hook-երը նման սահմանափակումներ չունեն - դրանք կատարվում են լիարժեք shell մուտքով:
Փաստաթղթերը խորհուրդ են տալիս այս պրակտիկաները.
- Երբեք հավաստագրեր մի պահեք hook հրամաններում
- Օգտագործեք շրջակա միջավայրի փոփոխականներ զգայուն տվյալների համար
- Հաստատեք բոլոր մուտքերը ${...} ընդլայնումներից
- Կիրառեք ժամկետային սահմանափակումներ արտաքին ծառայությունների համար
- Օգտագործեք async hook-եր ոչ-կրիտիկական գործողությունների համար, որպեսզի կանխեք ձախողումների արգելափակումը
Hook Կատարման Մեկուսացում
Օգտատիրոջ մակարդակի hook-երը ~/.claude/settings.json-ում կիրառվում են բոլոր նախագծերում։ Սա ռիսկեր է ստեղծում տարբեր վստահության սահմաններում աշխատելիս։ Նախագծային մակարդակի hook-երը գերակշռում են օգտատիրոջ hook-երը, բայց չեն կարող ամբողջովին անջատել դրանք:
Claude Code-ի /hooks մենյուն ցույց է տալիս բոլոր ակտիվ hook-երը ընթացիկ նստաշրջանի համար։ Այս ցուցակը վերանայելը՝ զգայուն նախագծերի վրա աշխատելուց առաջ, օգնում է բացահայտել պոտենցիալ անվտանգության մտահոգությունները:
Debugging և Մտահանգում
Hook-ի ձախողումները միշտ չէ, որ հստակ երևում են Claude-ի զրույցում։ Պաշտոնական փաստաթղթերը տրամադրում են մի քանի debugging մոտեցումներ:
Hook Կատարման Գրանցումներ
Claude Code-ը գրանցում է hook-ի կատարումը նստաշրջանի debug ելքին։ Ըստ troubleshooting ուղեցույցի, debug գրանցման միացումը բացահայտում է:
- Որ hook-երն են համընկել յուրաքանչյուր իրադարձության համար
- JSON մուտքը, որը ուղարկվել է յուրաքանչյուր hook-ին
- Stdout և stderr ելքը hook գործընթացներից
- Exit կոդերը և կատարման ժամանակը
- HTTP պատասխանի կոդերը և մարմինները HTTP hook-երի համար
Միացրեք debug գրանցումը՝ սահմանելով CLAUDE_DEBUG=1 շրջակա միջավայրում՝ Claude Code-ը գործարկելուց առաջ:
Hook-երի Անկախ Փորձարկում
Հրամանային hook-երը կարող են փորձարկվել Claude Code-ից դուրս՝ ձեռքով կառուցելով JSON մուտք:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Սա հաստատում է hook տրամաբանությունը՝ չգործարկելով Claude-ի իրական գործողությունները։ Exit code-ը և stdout/stderr ելքը պետք է համապատասխանեն սպասվող վարքագծին:
Ընդհանուր Hook Ձախողումներ
Համայնքային քննարկումները բացահայտում են այս հաճախակի խնդիրները:
- Timeout սխալներ. 10-րոպեանոց լռելյայն ժամկետը չափազանց կարճ է դանդաղ գործողությունների համար - ավելացրեք timeout դաշտով
- Path ընդլայնման ձախողումներ. Փոփոխականները, ինչպիսիք են ${file}, անորոշ են այն իրադարձությունների համար, որոնք չեն ներառում ֆայլային կոնտեքստ
- Թույլտվության սխալներ. Hook սկրիպտներին բավարար կատարման թույլտվություններ չկան - կատարեք chmod +x script.sh
- JSON վերլուծման սխալներ. Hook-երից ոչ պատշաճ JSON ելք - հաստատեք jq-ով՝ նախքան վերադարձնելը
- Շրջակա միջավայրի փոփոխականների անմատչելիություն. Փոփոխականները չեն փոխանցվում hook գործընթացին - ստուգեք Claude Code-ի միջավայրը
Hook Կատարողականության Հետևանքներ
Սինխրոն hook-երը արգելափակում են Claude-ի աշխատանքային հոսքը մինչև ավարտը։ Լռելյայն 10-րոպեանոց ժամկետը կանխում է անվերջ կախումները, բայց նույնիսկ կարճ ուշացումները կուտակվում են բազմաթիվ գործողությունների ընթացքում:
Գործնական մասնագետները հաղորդում են, որ պարզ հաստատման hook-երը ունեն աննշան կատարողականության ազդեցություն։ Ֆայլերի ձևավորման hook-երը առաջացնում են նկատելի, բայց ընդունելի կատարողականության ազդեցություն։ Արտաքին API-ի կանչերը կարող են ստեղծել աշխատանքային հոսքի խոչընդոտներ։ Ծանր հաշվողական գործողությունները օգուտ են ստանում ասինխրոն կատարումից:
Hook Փաթեթավորում
Բազմաթիվ hook-եր կարող են համընկնել նույն իրադարձության հետ։ Ըստ հղման փաստաթղթերի, hook-երը կատարվում են հաջորդաբար՝ սահմանման կարգով։ Եթե որևէ hook արգելափակի գործողությունը, մնացած hook-երը չեն կատարվի:
Սա կարևոր է կատարողականության համար։ Հինգ սինխրոն hook յուրաքանչյուրը 200 մմ-ով ավելացնում է մեկ վայրկյան մեկ իրադարձության համար։ Առնչվող հաստատումները մեկ hook-ում համատեղելը նվազեցնում է ավելորդ ծախսը:
Advanced Ձևեր
Հիմնական ավտոմատացումից դուրս, hook-երը թույլ են տալիս բարդ աշխատանքային հոսքի հարմարեցում:
Stateful Hook Շղթաներ
Hook-երը կարող են պահպանել վիճակը՝ կատարումների միջև՝ օգտագործելով ֆայլեր կամ բազաներ։ PostToolUse hook-ը կարող է գրանցել հաջողված գործողությունները, որոնք PreToolUse hook-ը հետագայում կհաստատի:
| #!/bin/bash # Record successful edits echo “${toolInput.path}” >> .claude/edit-history.txt |
Ուղեկից PreToolUse hook-ը կարող է ստուգել այս պատմությունը՝ կանխելու կրկնվող գործողությունները կամ կիրառելու կարգի սահմանափակումներ:
Պայմանական Hook Ակտիվացում
Շրջակա միջավայրի փոփոխականները վերահսկում են hook-երի վարքագիծը կատարման ժամանակ։ CLAUDE_SKIP_HOOKS=1-ը սահմանելը անջատում է hook-երը արտակարգ իրավիճակների համար:
Hook-երն ինքները կարող են ստուգել շրջակա միջավայրի դրոշակները:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Apply strict validation exit 1 fi exit 0 |
Սա թույլ է տալիս մշակման ռեժիմը ընդդեմ արտադրական ռեժիմի վարքագծի՝ առանց կարգաւորման փոփոխությունների:
Բազմափուլ Հաստատում
PreToolUse hook-երը կարող են իրականացնել բազմաշերտ հաստատում, որտեղ exit code 2-ը թույլ է տալիս Claude-ին շարունակել զգուշացումներով:
- Կոշտ ձախողումներ (exit 1). Արգելափակում է վտանգավոր գործողությունները
- Փափուկ զգուշացումներ (exit 2). Ծանուցում է Claude-ին՝ վերանայելու համար
- Անցում կոնտեքստով (exit 0 + JSON). Լրացուցիչ տեղեկատվություն է տրամադրում
Սա ստեղծում է հաստատման սպեկտր, որն ավելի նրբորեն է, քան binary թույլատրել/հրաժարվել:
Ինտեգրում CI/CD-ի Հետ
Ըստ պաշտոնական պլատֆորմի ինտեգրման փաստաթղթերի, Claude Code-ը գործարկվում է CI/CD միջավայրերում՝ ավտոմատացված կոդի վերանայման և խնդիրների վերլուծման համար։ Hook-երը ընդլայնում են այս ավտոմատացումը:
GitHub Actions աշխատանքային հոսքերը կարող են սահմանել hook-եր, որոնք կիրառում են թիմային քաղաքականություններ ավտոմատացված նստաշրջանների ընթացքում:
| – name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
STRICT_MODE դրոշը ակտիվացնում է պայմանական հաստատման տրամաբանությունը hook սկրիպտներում։ Սա ապահովում է, որ ավտոմատացված նստաշրջանները հետևեն ավելի կոշտ կանոններին, քան ինտերակտիվ մշակումը:
Աուդիտային Հետքի Ստեղծում
PostToolUse hook-երը CI միջավայրերում ստեղծում են Claude-ի բոլոր գործողությունների մանրամասն աուդիտային գրանցամատյաններ:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Ֆոնային գրանցումը չի ազդում կատարողականության վրա, բայց ապահովում է գործողությունների ամբողջական պատմություն համապատասխանության և debugging-ի համար:
The /hooks Մենյու
Claude Code-ը տրամադրում է /hooks հրաման, որը ցույց է տալիս բոլոր ակտիվ hook-երը ընթացիկ նստաշրջանի համար։ Ըստ պաշտոնական փաստաթղթերի, այս մենյուն ցույց է տալիս:
- Hook իրադարձության տեսակը
- Մատչերի ձևաչափերը
- Հրամանը կամ URL վերջակետը
- Արդյո՞ք hook-ը կատարվում է async
- Կարգաւորման աղբյուրը (նախագիծ, օգտատեր կամ plugin)
Hook-ը ընտրելը ցույց է տալիս դրա ամբողջական կարգաւորումը և թույլ է տալիս ժամանակավորապես անջատել այն ընթացիկ նստաշրջանի համար:
Անջատել կամ Հեռացնել Hook-երը
Hook-երը կարող են անջատվել՝ առանց կարգաւորումը հեռացնելու՝ ավելացնելով "enabled": false hook-ի սահմանմանը։ Սա պահպանում է կարգաւորումը՝ միաժամանակ կանխելով կատարումը:
Hook-ը մշտապես հեռացնելու համար, ջնջեք դրա գրառումը համապատասխան settings.json ֆայլից։ Փոփոխությունները ուժի մեջ են մտնում հաջորդ նստաշրջանի վերսկսումից կամ /reload կատարելուց հետո:
Hook-եր Գիտելիքներում և Գործակալներում
Ըստ պաշտոնական փաստաթղթերի, գիտելիքի կամ ենթագործակալի կարգաւորումներում սահմանված hook-երը կիրառվում են միայն այն ժամանակ, երբ այդ գիտելիքը կամ գործակալը կատարվում է։ Սա թույլ է տալիս մասնագիտացված ավտոմատացում կոնկրետ աշխատանքային հոսքերի համար:
Debugging ենթագործակալը կարող է ներառել hook-եր, որոնք գրանցում են բոլոր գործիքային կանչերը:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Այս hook-երը կատարվում են միայն debugger գործակալի նստաշրջանների ընթացքում, ոչ թե Claude Code-ի սովորական գործողության ժամանակ:
Հղում Scripts Ուղուց
Hook հրամանները աջակցում են ինչպես հարաբերական, այնպես էլ բացարձակ ուղիներ։ Հարաբերական ուղիները լուծվում են նախագծի արմատից, որտեղ 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 սկրիպտներում
Ապագա Hook Հնարավորություններ
GitHub-ի հատկությունների խնդրանքները բացահայտում են պլանավորված և խնդրված hook բարելավումներ:
- Inline script hook-եր. Hook տրամաբանությունը սահմանեք ուղղակի settings.json-ում՝ առանց արտաքին ֆայլերի
- MCP գործիքային ինտեգրում. MCP սերվերի գործիքներ կանչեք hook-երից՝ shell հրամանների փոխարեն
- Բազմագործակալ համագործակցություն. Hook-եր, որոնք համակարգում են Claude-ի ինստանսների միջև տարբեր մեքենաներում
- Բարելավված types. TypeScript տիպի սահմանումներ hook մուտքային/ելքային սխեմաների համար
Ըստ GitHub issue #4274-ի, ինտեգրված hook տեսակների (MCP գործիք, inline script, API կանչ) խնդրանքը նպատակ ունի պարզեցնել կարգաւորումը և բարելավել մշակողի փորձը:
Հաճախ Տրվող Հարցեր
Կարո՞ղ են hook-երը կանխել Claude-ին վտանգավոր հրամաններ կատարելուց։
Այո։ PreToolUse hook-երը կարող են արգելափակել ցանկացած գործիքի կատարում՝ ավարտվելով 1 կոդով։ Սա ներառում է ֆայլերի խմբագրում, հրամանների կատարում և MCP գործիքային կանչեր։ Hook-ը ստանում է գործիքի ամբողջական մուտքը և կարող է հաստատել ցանկացած չափանիշի դեմ՝ նախքան գործողությունը թույլատրելը:
Ինչպե՞ս debug անել hook, որը չի աշխատում։
Միացրեք debug գրանցումը CLAUDE_DEBUG=1-ով՝ Claude Code-ը գործարկելուց առաջ։ Ստուգեք նստաշրջանի գրանցումները hook-ի կատարման մանրամասների համար, ներառյալ, թե որ hook-երն են համընկել, ուղարկված JSON մուտքը, stdout/stderr ելքը և exit կոդերը։ Անկախ փորձարկեք hook-երը՝ փոխանցելով նմուշային JSON hook սկրիպտին:
Hook-երն աշխատո՞ւմ են Claude Code-ի բոլոր պլատֆորմների հետ։
Hook-երը աշխատում են CLI, desktop app, և VS Code extension-ներում։ Ըստ պաշտոնական փաստաթղթերի, hook-երը կատարվում են այնտեղ, որտեղ Claude Code-ը գործում է՝ ֆայլային համակարգի մուտքով։ Թերթի վրա հիմնված Claude-ը և բջջային հավելվածները չեն աջակցում hook-երին՝ sandbox-ի սահմանափակումների պատճառով:
Կարո՞ղ են hook-երը փոփոխել Claude-ի պատասխանները կամ վարքագիծը։
Prompt hook-երը ներարկում են հրահանգներ, որոնք ազդում են Claude-ի վարքագծի վրա։ Agent hook-երը իրադարձությունների մշակումը պատվիրակում են մասնագիտացված ենթագործակալներին։ Այնուամենայնիվ, hook-երը չեն կարող ուղղակիորեն փոփոխել Claude-ի ստեղծած տեքստը կամ մտահանգման գործընթացը - նրանք աշխատում են՝ տրամադրելով կոնտեքստ և արգելափակելով գործողությունները:
Ո՞րն է async և sync hook-երի տարբերությունը։
Սինխրոն hook-երը արգելափակում են Claude-ի աշխատանքային հոսքը մինչև ավարտը կամ ժամկետի լրանալը։ Ասինխրոն hook-երը կատարվում են ֆոնային ռեժիմում՝ առանց արգելափակման։ Sync hook-երը կարող են կանխել գործողությունները՝ ելքային կոդերի միջոցով։ Async hook-երը չեն կարող արգելափակել, քանի որ Claude-ը շարունակում է hook-ի ավարտից առաջ։ Օգտագործեք async logging-ի և ծանուցումների համար, sync հաստատման համար:
Ինչպե՞ս համօգտագործել hook-երը թիմի հետ։
Ներկայացրեք .claude/settings.json ֆայլը տարբերակի վերահսկմանը։ Նախագծային մակարդակի hook-երը կիրառվում են բոլոր թիմի անդամների վրա, ովքեր դեպոզիտարիան են քլոնում։ Կազմակերպության մակարդակի քաղաքականությունների համար թիմերը կարող են պահպանել ընդհանուր օգտատիրոջ մակարդակի settings ֆայլ, որը անդամները պատճենում են ~/.claude/settings.json-ին:
Կարո՞ղ են HTTP hook-երը կանչել ներքին API-ներ հրդեհային պատերի ետևում։
Այո, եթե Claude Code-ը գործում է այնպիսի միջավայրում, որն ունի ցանցային մուտք այդ API-ներին։ HTTP hook-երը կատարում են ստանդարտ POST հարցումներ Claude Code-ը գործարկող մեքենայից։ Կորպորատիվ հրդեհային պատերը և VPN-ները կիրառվում են սովորաբար։ Sandbox proxy-ն, որը նշված է փաստաթղթերում, վերահսկում է շրջակա միջավայրի փոփոխականների բացահայտումը, ոչ թե ցանցային երթևեկությունը:
Hook-երը մեծացնո՞ւմ են Claude Code-ի token-ի օգտագործումը։
Prompt hook-երը տեքստ են ներարկում Claude-ի կոնտեքստի մեջ, որը սպառում է tokens։ Հրամանային և HTTP hook-երը չեն ազդում token-ի օգտագործման վրա, բայց դրանց ելքը (սխալի հաղորդագրություններ, առաջարկներ) դառնում է զրույցի կոնտեքստի մաս։ Exit code 2-ը՝ բացատրական հաղորդագրություններով, ավելի շատ կոնտեքստ է ավելացնում, քան exit code 1-ը՝ պարզ արգելափակմամբ:
Եզրակացություն
Claude Code hook-երը AI օգնականը վերածում են հզոր գործիքից լիովին ավտոմատացված մշակման պլատֆորմի։ Իրադարձությունների համակարգը միջամտության կետեր է տրամադրում Claude-ի աշխատանքային հոսքի ընթացքում՝ նստաշրջանի նախաձեռնումից մինչև կոնտեքստի կոմպակտացում:
Հրամանային hook-երը մշակում են տեղական հաստատում և ձևավորում։ HTTP hook-երը ինտեգրում են արտաքին ծառայություններ և բազաներ։ Prompt hook-երը փոփոխում են վարքագիծը՝ կոնտեքստի ներարկման միջոցով։ Միասին, դրանք հնարավորություն են տալիս ավտոմատացման ձևեր, որոնք կիրառում են թիմային քաղաքականություններ, պահպանում կոդի որակը և ինտեգրվում են գոյություն ունեցող մշակման ենթակառուցվածքի հետ:
Մատչերի համակարգը զտում է hook-երը կոնկրետ գործիքների և ֆայլային ձևերի համար։ Exit կոդերը և JSON ելքը վերահսկում են որոշումների հոսքը։ Ասինխրոն կատարումը կանխում է դանդաղ գործողությունների արգելափակումը։ Ամբողջական կարգաւորման սխեման աջակցում է ամեն ինչից՝ պարզ ավտո-ձևավորումից մինչև բարդ բազմափուլ հաստատում:
Սկսեք պարզ PostToolUse hook-երով՝ կոդի ձևավորման համար։ Ավելացրեք PreToolUse հաստատում, երբ քաղաքականությունները սկսեն առաջանալ։ Փորձարկեք prompt hook-երը վարքագծի փոփոխության համար։ Կառուցեք HTTP ինտեգրումներ՝ թիմի մակարդակով կիրառման համար:
Ստուգեք Claude Code-ի պաշտոնական փաստաթղթերը՝ ամբողջական hooks հղման և թարմացված կարգաւորման սխեմայի համար, քանի որ նոր հնարավորություններ են թողարկվում:
