Claude Code Hooks: কীভাবে কাজ করে ও কেন দরকার
Claude Code hooks model-এর সম্মতি ছাড়াই চলে। কোথায় থাকে, কোন event কখন fire হয়, exit code 2 কীভাবে tool call বাতিল করে এবং security cost কী, জানুন।
Claude Code hook কী
Claude Code hook হলো এমন সব shell command যা Claude Code তার নিজস্ব lifecycle-এর নির্দিষ্ট কিছু সময়ে নিজে থেকেই চালায়। hook এবং rules file-এর মধ্যে মূল পার্থক্য এখানেই। CLAUDE.md-এর কোনো নির্দেশনা হলো পরামর্শ, যা model তার context-এর অন্যান্য তথ্যের সাথে মিলিয়ে বিবেচনা করে। অন্যদিকে, hook হলো code, যা model-এর মতামতের তোয়াক্কা না করেই কার্যকর হয়। যদি আপনার agent বারবার আপনার বলে দেওয়া formatter এড়িয়ে যায়, তবে তাকে আরও কঠোর নির্দেশনা দেওয়ার প্রয়োজন নেই। আপনার একটি hook প্রয়োজন।
এই প্রক্রিয়াটি বেশ সহজ। আপনি একটি settings file-এ event name-এর অধীনে একটি command register করবেন। যখন সেই event ঘটে, Claude Code আপনার command-টি চালায় এবং event-এর data-কে standard input (stdin)-এ JSON (JavaScript object notation) হিসেবে লিখে দেয়। আপনার command সেই data পড়ে, প্রয়োজনীয় কাজ সম্পন্ন করে এবং একটি exit status প্রদান করে। একটি PreToolUse hook থেকে exit 2 দিলে তা tool call-টি কার্যকর হওয়ার আগেই বাতিল করে দেয়। আপনার script standard error (stderr)-এ যা লেখে, তা-ই model-এর কাছে কারণ হিসেবে ফিরে যায়; তবে যদি hook-টি এমন কোনো JSON প্রিন্ট করে যাতে blocking decision থাকে, তবে সেই কারণটিই প্রাধান্য পায়।
এখানে উল্লিখিত event name এবং field name-গুলো Claude Code hooks reference থেকে নেওয়া হয়েছে, যা 12 নভেম্বর, 2026 তারিখে যাচাই করা হয়েছে। এই বিষয়টি দ্রুত পরিবর্তিত হয়, তাই যেকোনো blog post থেকে JSON কপি করার আগে আপনার নিজের version-এর জন্য reference যাচাই করে নিন। আপনার বর্তমান version দেখতে claude --version ব্যবহার করুন।
হুক কনফিগারেশন যেখানে থাকে
একটি হুক হলো সেটিংস ফাইলের ভেতরে থাকা একটি JSON ব্লক। ছয়টি স্থানে এটি থাকতে পারে এবং ফাইলের স্কোপই হলো হুকের স্কোপ।
~/.claude/settings.json: আপনার মেশিনের প্রতিটি প্রজেক্টের জন্য, অন্য কারো জন্য নয়।.claude/settings.json: একটি নির্দিষ্ট প্রজেক্টের জন্য, যা রিপোজিটরিতে কমিট করা থাকে, ফলে যারা এটি ক্লোন করবে তারা সবাই হুকটি পাবে।.claude/settings.local.json: একটি নির্দিষ্ট প্রজেক্টের জন্য, শুধুমাত্র আপনার মেশিনে।- ম্যানেজড পলিসি সেটিংস: পুরো প্রতিষ্ঠানের জন্য, একজন অ্যাডমিনিস্ট্রেটর দ্বারা নির্ধারিত।
hooks/hooks.jsonএকটি প্লাগইনের ভেতরে, যা প্লাগইনটি চালু থাকা অবস্থায় কার্যকর থাকে।- স্কিল বা সাব-এজেন্ট ফ্রন্টম্যাটার। একটি স্কিল একবার ইনভোক করা হলে সেশনের বাকি সময়জুড়ে এর হুকগুলো কার্যকর থাকে এবং সাব-এজেন্টের হুকগুলো সাব-এজেন্টটি চলাকালীন কার্যকর থাকে।
এই ফাইলগুলো থেকে আসা হুক এন্ট্রিগুলো একে অপরকে ওভাররাইড না করে মার্জ হয়। একটি প্রজেক্ট সেটিংস ফাইল আপনার ইউজার সেটিংসের হুকগুলোর সাথে নতুন হুক যোগ করে, সেগুলোকে প্রতিস্থাপন করে না; ফলে একটি ইভেন্টে বিভিন্ন ফাইল থেকে আসা একাধিক হুক থাকতে পারে। "disableAllHooks": true সেটিংটি চালু করলে এগুলো বন্ধ হয়ে যায়, তবে একটি ব্যতিক্রম আছে: ম্যানেজড পলিসি সেটিংস থেকে আসা হুকগুলো চলতে থাকে, যদি না সেই সেটিংটি ম্যানেজড সেটিংসের ভেতরেও প্রয়োগ করা হয়।
বর্তমানে নিবন্ধিত প্রতিটি হুক দেখার জন্য সেশনের ভেতরে /hooks চালান। এগুলো ইভেন্ট অনুযায়ী গ্রুপ করা থাকে এবং প্রতিটির সোর্স ফাইল ও ম্যাচিং রুল দেখানো হয়। মেনুটি শুধুমাত্র পড়ার জন্য (read only), তাই হুক পরিবর্তন করতে হলে সেটিংস ফাইলটি এডিট করতে হবে। ফাইল ওয়াচার সাধারণত রিস্টার্ট ছাড়াই এডিটগুলো শনাক্ত করে নেয়।
Claude Code-এ কোন hook event বিদ্যমান
Hooks reference-এ মোট তেত্রিশটি event তালিকাভুক্ত আছে। এগুলো SessionStart থেকে SessionEnd পর্যন্ত বিস্তৃত এবং compaction, subagent, worktree ও configuration file কভার করে। Server-এর কাজে এগুলোর কয়েকটি বেশি ব্যবহৃত হয়।
PreToolUse:EndConversationছাড়া কোনো tool call কার্যকর হওয়ার আগে। কোনো tool call আটকে দিতে পারে এমন এটিই একমাত্র event।PostToolUse:EndConversationছাড়া কোনো tool call সফল হওয়ার পরে। Tool call ব্যর্থ হলেPostToolUseFailureকার্যকর হয়। তাই প্রতিটি ফলাফল দেখতে হলে hook-এ দুটিই রাখতে হবে।PermissionRequest: কোনো tool call-এর জন্য permission সিদ্ধান্ত প্রয়োজন হলে। এই সময়েই approval prompt প্রদর্শিত হওয়ার কথা।UserPromptSubmit: আপনি prompt submit করার সময়, Claude সেটি process করার আগে। সফল hook-এর plain-text stdout model-এর context-এ যুক্ত হয়।SessionStartএবংSessionEnd: session-এর প্রতিটি প্রান্তে। Compaction-এর পরেওSessionStartকার্যকর হয়, যেখানে matcher value থাকেcompact।Stop: Claude response শেষ করলে। এটি প্রতি turn-এ একবার কার্যকর হয়, কাজ শেষ হলে একবার নয়।
যেসব event matcher সমর্থন করে, সেসব event-এ একটি group-এর সঙ্গে matcher থাকতে পারে। এটি নির্ধারণ করে কোন occurrence-এ hook কার্যকর হবে। Tool event-এ এটি tool name অনুযায়ী filter করে। তাই "Edit|Write" file edit-এর সময় কার্যকর হবে, অন্য কোনো ক্ষেত্রে নয়। Matcher case sensitive। খালি matcher প্রতিটি occurrence-এ কার্যকর হয়। MCP (model context protocol) server-এর tool-এর নাম mcp__<server>__<tool>। তাই "mcp__github__.*" matcher ব্যবহার করলে একটি server-এর tool ধরা পড়বে এবং অন্য server-গুলোর tool বাদ থাকবে।
Stop hook-এ এমন একটি বিষয় আছে, যা hook লেখার আগে জানা দরকার। কোনো Stop hook block করলে model-কে আবার কাজ করতে পাঠানো হয়। Claude Code ডিফল্টভাবে পরপর আটবার continuation-এর পরে পরবর্তী block override করে। Claude কোনো tool call করলেই এই গণনা আবার শুরু হয়। Hook input থেকে stop_hook_active field পড়ুন এবং সেটির মান true হলে exit 0 করুন। তা না হলে hook Claude-কে বারবার কাজে ফেরত পাঠাতে পারে।
stdin-এ hook কী গ্রহণ করে
Claude যখন npm test চালাতে যাচ্ছে, তখন Bash-এ থাকা PreToolUse hook stdin থেকে এটি পড়ে:
{
"session_id": "abc123",
"cwd": "/home/deploy/myproject",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test"
}
}সাধারণ input field-এর মধ্যে session_id, cwd, transcript_path এবং hook_event_name থাকে; প্রতিটি event-এ permission_mode পাঠানো হয় না। Tool event-এ tool_name, tool_input এবং tool_use_id যোগ হয়। অন্যান্য event-এ নিজস্ব field থাকে: UserPromptSubmit-এ prompt text পাওয়া যায়, আর SessionStart-এ startup, resume, clear, compact অথবা fork-এর একটি source পাওয়া যায়।
Shell script-এর ভিতরে এটি পড়ার প্রচলিত উপায় হলো jq, তবে minimal server image-এ এটি থাকে না। Ubuntu এবং Debian-এ প্রথমে sudo apt install -y jq দিয়ে এটি install করুন।
টুল কল চলমান অবস্থায় exit status-এর প্রভাব
এখানে তিনটি ফলাফল হতে পারে।
- Exit 0 সফলতা নির্দেশ করে। বৈধ JSON decision field থাকলে সেগুলো কার্যকর হয়, যার মধ্যে block বা denial-ও রয়েছে।
PreToolUse-এ exit 0 হলেও কোনো decision না থাকলে সেটিকে approval ধরা হয় না; স্বাভাবিক permission flow তখনও চলে।UserPromptSubmit,UserPromptExpansion,SessionStartএবংPostModelSwitch-এ plain-text stdout model-এর context-এ যোগ হয়। অন্যান্য অধিকাংশ event-এ stdout শুধু debug log-এ যায়। - Exit 2 যেসব event-এ action block করা যায়, সেগুলোতে action block করে;
PreToolUseতার মধ্যে রয়েছে। stderr block-এর সঙ্গে দেখানো message হয়ে যায়, তবে JSON output-এ blocking decision থাকলে তার reason অগ্রাধিকার পায়। এই message কে দেখবে, তা event-এর ওপর নির্ভর করে।PreToolUseএবংStop-এ model এটি reason হিসেবে দেখে।UserPromptSubmitএবংPreModelSwitch-এ এটি আপনাকে দেখানো হয় এবং model-এর context-এ যোগ হয় না।PostToolUseএবংPostToolUseFailureblock করা যায় না; সেখানে block উপেক্ষা করা হয়, তবে stderr feedback হিসেবে model-এর কাছে পৌঁছায়। block করা যায় না এমন অন্যান্য অধিকাংশ event-এ stderr শুধু আপনাকে দেখানো হয় অথবা উপেক্ষা করা হয়।Stop,SubagentStop,TaskCompletedএবং কোনো plugin-এরUserPromptSubmithook-এ stdout খালি থাকলে এবং stderr-এ missing-file error থাকলে exit 2-কে non-blocking error হিসেবে ধরা হয়। - অন্য যেকোনো exit code-এর সঙ্গে plain-text বা খালি stdout থাকলে সেটিকে সাধারণত non-blocking error ধরা হয়। Transcript-এ
Failed with non-blocking status code:-এর পর stderr-এর প্রথম line-সহ একটি hook error notice দেখানো হয়।PreToolUse-এর মতো event-এ বৈধ JSON এখনও ফলাফল নির্ধারণ করতে পারে, যদি hook-এর ব্যর্থতা action block না করে।WorktreeCreateযেকোনো nonzero exit-এ ব্যর্থ হয়।WorktreeRemove-এ nonzero exit হলে directory তখনও বিদ্যমান থাকলে এটি ব্যর্থ হয়।
Block করা বা নীরব থাকার বাইরে অন্য কোনো ফলাফল দরকার হলে exit 0 ব্যবহার করুন এবং stdout-এ একটি JSON object print করুন। PreToolUse hook permissionDecision দিয়ে সিদ্ধান্ত নেয়:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database drops go through a migration, not through the agent."
}
}"allow" permission rules এবং tool-এর approval requirements অনুমতি দিলে interactive prompt বাদ দেয়, "deny" call বাতিল করে এবং reason model-কে পাঠায়, আর "ask" confirmation চায়। প্রতিটি hook-এর জন্য একটি style বেছে নিন। stdout-এ JSON decision দেওয়ার সঙ্গে exit 2 ব্যবহার করলেও block বজায় থাকে, JSON-এ "allow" বলা থাকলেও।
একটি event-এর সঙ্গে একাধিক hook মিললে সেগুলো parallel-এ চলে; prompt এবং agent hook একসঙ্গে সর্বোচ্চ বারোটি চলতে পারে। কোনো একটি hook-এর deny তার sibling hook-গুলোর execution বন্ধ করে না। তাই guardrail hook একই call deny করলেও logging hook তার line লিখতে পারে। PreToolUse-এর ক্ষেত্রে Claude Code পরে উত্তরগুলো merge করে এবং সবচেয়ে restrictive ফলাফল রাখে। অগ্রাধিকারের ক্রম হলো deny, defer, ask, allow।
উদাহরণ 1: চালানোর আগে একটি ধ্বংসাত্মক কমান্ড ব্লক করুন
এটি আপনার project-এ .claude/hooks/block-destructive.sh নামে সংরক্ষণ করুন:
#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
exit 2
fi
done
exit 0এটিকে executable করুন। এরপর .claude/settings.json-এর PreToolUse-এ এটি নিবন্ধন করুন:
chmod +x .claude/hooks/block-destructive.sh{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
"timeout": 10,
"statusMessage": "Checking the command against policy"
}
]
}
]
}
}স্ক্রিপ্টটির ওপর আস্থা রাখার আগে হাতে চালিয়ে পরীক্ষা করুন। কারণ onFailure unset থাকলে, নিজের input-এ crash করা hook সাধারণত fail open করে। Git Bash ছাড়া Windows-এ ব্যর্থ shell-form PreToolUse বা PermissionRequest command hook-এর পরিবর্তে tool call-টিও ব্লক করতে পারে:
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
| .claude/hooks/block-destructive.sh
echo $?stderr-এ Blocked by policy: line এবং 2 exit code দেখা উচিত। ls -la-এর মতো একটি harmless command পাঠালে কোনো output দেখা উচিত নয় এবং exit code হবে 0। একটি session-এ denied call-টি transcript-এ আপনার message-কে কারণ হিসেবে দেখাবে। Model সেই message পড়ে আচরণ সামঞ্জস্য করে।
একটি বৈশিষ্ট্যের কারণে এটি ব্যবহার করা মূল্যবান: PreToolUse hook সব permission mode-এ permission-mode check-এর আগে চলে। তাই bypassPermissions চালু থাকলেও deny কার্যকর থাকে। এ কারণেই Claude Code-এর auto mode এবং এর permission settings-এর পাশাপাশি hook কার্যকর। সেখানে prompt কম দেখানো হলেও hook চলতে থাকে।
এটি কী, সে বিষয়ে সঠিক ধারণা রাখুন। Command string-এর ওপর pattern matching agent-এর অসতর্কতার বিরুদ্ধে একটি guardrail। তবে এটি agent-এর কৌশলী আচরণের বিরুদ্ধে boundary নয়। একই command এমনভাবে লেখা যেতে পারে, যা আপনার grep কখনো দেখতে পায় না। কঠোর নিয়ম permission system-এ এবং যে account-এর অধীনে process চলে, সেখানে প্রয়োগ করা উচিত।
উদাহরণ 2: প্রতিটি সম্পাদনার পরে format এবং lint চালান
PostToolUse-এর সঙ্গে একটি Edit|Write matcher ব্যবহার করলে ওই দুই file-editing tool-এর যেকোনো একটি সফলভাবে শেষ হওয়ার পরে এটি চলে। এটি .claude/hooks/after-edit.sh হিসেবে সংরক্ষণ করুন:
#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0
case "$FILE" in
*.py)
ruff format "$FILE" >/dev/null 2>&1
if ! ruff check "$FILE" >&2; then
exit 2
fi
;;
*.sh)
if ! shellcheck "$FILE" >&2; then
exit 2
fi
;;
esac
exit 0{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
"timeout": 60
}
]
}
]
}
}Claude-কে একটি Python file-এ ভুল indentation-সহ একটি function যোগ করতে বলুন। এরপর file-টি খুলুন। File-টি formatted অবস্থায় ফিরে আসবে। এটিই hook চলার যাচাই। কারণ hook সফল হলে conversation-এ কিছুই দেখায় না।
এখানে exit 2 কোনো পরিবর্তন বাতিল করে না। PostToolUse tool ইতিমধ্যে execution শেষ করার পরে চলে। তাই যেকোনো অবস্থাতেই edit disk-এ লেখা থাকে। exit 2-এর সুবিধা হলো, ruff check-এর output feedback হিসেবে model-এর কাছে পৌঁছে যায়। ফলে এটি সদ্য তৈরি করা error ঠিক করে, পরবর্তী কাজে চলে যায় না। commit-এর সময় শনাক্ত হওয়া lint failure এবং agent একই turn-এ ঠিক করে দেওয়া lint failure-এর মধ্যে এটাই পার্থক্য।
এখানে matcher-এর দুটি সীমাবদ্ধতা গুরুত্বপূর্ণ। Edit|Write shell command-এর মাধ্যমে পরিবর্তিত file দেখতে পায় না। Claude যথেষ্ট ঘন ঘন Bash-এর মাধ্যমে file লেখে, তাই এই সীমাবদ্ধতা বাস্তব সমস্যা তৈরি করে। প্রতিটি call-এ coverage নিশ্চিত করতে Bash-এর সঙ্গেও match করুন এবং script-কে git status --porcelain দিয়ে পরিবর্তিত file-এর তালিকা তৈরি করতে দিন। প্রতিটি turn-এ একবার coverage চাইলে scan-টি পরিবর্তে একটি Stop hook-এ রাখুন।
উদাহরণ 3: audit-এর জন্য প্রতিটি tool call log করুন
PostToolUse-এ একটি খালি matcher থাকলে EndConversation ছাড়া প্রতিটি সফল tool call-এর সময় এটি কার্যকর হয়। রেকর্ডটি home directory-এর কোনো file-এ না লিখে system journal-এ পাঠালেও agent-এর নিজস্ব shell থেকে সেটি অগম্য হয় না: access নির্ভর করে account-এর permission-এর ওপর। Users তাদের private per-user journal পড়তে পারে। এছাড়া root এবং systemd-journal, adm বা wheel-এর সদস্যরা সব journal file পড়তে পারে:
{
"hooks": {
"PostToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
}
]
}
]
}
}journalctl -t claude-code -o cat | tail -n 5 দিয়ে এটি আবার পড়ুন। রেকর্ড পড়ার permission থাকলে EndConversation ছাড়া প্রতিটি সফল tool call-এর জন্য একটি করে JSON line দেখা উচিত, যেখানে সর্বশেষটি শেষে থাকবে। কিছু দেখা না গেলে hook কার্যকর হয়েছে কি না দেখার পাশাপাশি journal access-ও পরীক্ষা করুন। নিচের troubleshooting section-এ hook সম্পর্কিত নির্দেশনা রয়েছে।
ব্যর্থ call-গুলোও capture করতে PostToolUseFailure-এর অধীনে একই block যোগ করুন। কারণ PostToolUse শুধু success-এর সময় কার্যকর হয়, অথচ failed command-ই সাধারণত বেশি গুরুত্বপূর্ণ। home directory-এর file-এ append করার পরিবর্তে logger ব্যবহারের কারণ ownership: hook agent-এর shell-এর মতো একই user হিসেবে চলে। তাই ওই user যে file-এ append করতে পারে, সেটি truncate-ও করতে পারে। systemd-journald journal লেখে; তবে deletion থেকে journal সুরক্ষিত থাকবে কি না, তা এখনও agent account-এর privilege-এর ওপর নির্ভর করে।
একটি hook কতক্ষণ চলতে পারে
এই চার্টের পেছনের ডেটা
[
{
"label": "command, http or mcp_tool hook",
"default_timeout_seconds": 600
},
{
"label": "agent hook",
"default_timeout_seconds": 60
},
{
"label": "prompt hook",
"default_timeout_seconds": 30
},
{
"label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
"default_timeout_seconds": 30
},
{
"label": "command, http or mcp_tool on MessageDisplay",
"default_timeout_seconds": 10
},
{
"label": "any hook on SessionEnd",
"default_timeout_seconds": 1.5
}
]একটি command hook ডিফল্টভাবে 600 seconds পায়, অর্থাৎ দশ মিনিট। কিছু event এই সময়সীমা অনেক কমিয়ে দেয়। SessionEnd hooks সবাই মিলে 1.5 seconds-এর একটি shared budget ব্যবহার করে। তাই end-of-session cleanup দ্রুত শেষ করতে হয়। তবে settings file-এ কোনো hook-এর জন্য দীর্ঘতর timeout সেট করলে এই shared budget-ও সেই অনুযায়ী বাড়ে, সর্বোচ্চ 60 seconds পর্যন্ত।
কোনো synchronous command, HTTP বা MCP tool hook timeout-এ পৌঁছালে সেটি বাতিল হয় এবং সাধারণত কোনো decision তৈরি করে না। তবে PreModelSwitch-এ timeout switch-টি আটকে দেয়। কোনো PreToolUse guardrail-এর ক্ষেত্রে timeout সাধারণত tool call-কে স্বাভাবিক permission flow-এ এগিয়ে যেতে দেয়। তবে onFailure unset থাকলে উপরের Windows ব্যতিক্রম প্রযোজ্য হয়। এই কারণে guardrail script ছোট রাখুন। release 2.1.295 থেকে command বা http hook-এ "onFailure": "block" ব্যবহার করে এই default পরিবর্তন করা যায়। এতে timeout, crash বা অপ্রত্যাশিত exit code block হিসেবে গণ্য হয়। তবে এর কোনো প্রভাব Stop, SubagentStop, TaskCompleted, TeammateIdle বা background command hook-এর ওপর পড়ে না। কোনো ধীর কাজের জন্য, যেমন কোনো log অন্যত্র পাঠানোর ক্ষেত্রে, যেখানে কারও অপেক্ষা করার প্রয়োজন নেই, "async": true সেট করুন। তাহলে tool call আটকে না রেখে hook background-এ চলবে।
Hooks, rules file, skill এবং MCP server
চারটি বিষয় একে অপরের সঙ্গে গুলিয়ে যায়, কারণ এগুলো প্রত্যেকটিই agent-এর আচরণ পরিবর্তন করে। তবে suggestion হিসেবে গণ্য না হওয়ার বৈশিষ্ট্য কেবল একটির আছে।
একটি rules file (CLAUDE.md, অথবা .claude/rules/-এর অধীনে থাকা কোনো file) হলো model-এর context-এ লোড হওয়া text। এটি আচরণকে প্রভাবিত করে, কিন্তু কোনো কিছু enforce করে না। দীর্ঘ conversation, বড় diff এবং ব্যবহারকারীর নতুন request-এর সঙ্গে প্রতিযোগিতায় এর একটি line গুরুত্ব হারাতে পারে। আপনার লিখে রাখা নির্দেশনা agent উপেক্ষা করার পেছনে সাধারণত এই প্রক্রিয়াই কাজ করে।
একটি skill হলো instruction এবং script-এর folder, যা model প্রাসঙ্গিক মনে করলে লোড করে। এই বিচারই skill-এর মূল বৈশিষ্ট্য এবং সীমাবদ্ধতাও: সিদ্ধান্তটি এখনও model-ই নেয়। Ponytail-এর মতো skill-এ এই দুই দিকই দেখা যায়। এটি এমনভাবে পুরো task পরিচালনার পদ্ধতি নির্ধারণ করে, যা কোনো hook পারে না; তবে model skill-টি লোড করার সিদ্ধান্ত নিলেই তা কার্যকর হয়।
একটি MCP (model context protocol) server model-কে call করার জন্য নতুন tool দেয়। এটি agent যে সংস্থানগুলিতে পৌঁছাতে পারে, তার পরিসর বাড়ায়। তবে এটি agent-কে কোনো কিছু ব্যবহার করতেই বাধ্য করে না। এটি একটি আলাদা process, যেটি আপনাকে পরিচালনা করতে হয়। সেটি নিজেই একটি পৃথক কাজ: VPS-এ MCP server চালানো দেখুন।
চারটির মধ্যে hook-ই একমাত্র ব্যবস্থা, যা model-এর সিদ্ধান্ত ছাড়াই চলে। কোনো preference-এর জন্য rules file ব্যবহার করুন। Model-এর ক্ষেত্রে প্রযোজ্য হলে অনুসরণ করা উচিত এমন procedure-এর জন্য skill ব্যবহার করুন। যে step প্রতিবার অবশ্যই চলতে হবে, অথবা যে কাজটি কখনোই করা যাবে না, তার জন্য hook ব্যবহার করুন। কখন skill rules file-এর চেয়ে ভালো, সেটিসহ বিস্তারিত তুলনা skill, MCP এবং rules file-এর তুলনায় রয়েছে।
Plugin হলো পঞ্চম কোনো mechanism নয়; এটি packaging। এটি hook এবং skill-কে একটি installable unit-এ একত্র করে। এভাবেই একটি team প্রতিটি machine-এ একই guardrail deploy করতে পারে: Claude Code plugin কীভাবে কাজ করে দেখুন।
একটি shared VPS-এ নিরাপত্তার সিদ্ধান্ত
hook হলো এমন কোড যা এজেন্ট trigger করে এবং এটি সেই ব্যবহারকারীর পরিচয়ে চলে যিনি Claude Code শুরু করেছেন। এটি সেই ব্যবহারকারীর file permission এবং environment উত্তরাধিকারসূত্রে পায়। ল্যাপটপের ক্ষেত্রে এটি একটি workflow-এর বিষয়। কিন্তু যে VPS-এ এজেন্ট কোনো তদারকি ছাড়াই চলে, সেখানে এটি চারটি ব্যবহারিক দিক থেকে একটি নিরাপত্তার প্রশ্ন।
repository-তে থাকা hook আপনার লেখা কোড নয়। .claude/settings.json commit করা থাকে, তাই কোনো repository clone করে তার ভেতরে session শুরু করলে repository-র সাথে আসা hook-গুলো register হয়ে যেতে পারে। interactive session-এ, Claude Code সেই ফোল্ডারের জন্য workspace trust dialog-এর মাধ্যমে project hook-গুলোকে আটকে রাখে, যার অর্থ হলো trust গ্রহণ করার মাধ্যমেই আপনি সেগুলো চালানোর সিদ্ধান্ত নিচ্ছেন। প্রথমে hooks ব্লকটি পড়ুন। একটি claude -p বা SDK session, যা সাধারণত unattended agent হিসেবে চলে, সেখানে এই dialog কখনোই দেখায় না এবং ফোল্ডারটিকে trusted হিসেবে বিবেচনা করে, ফলে repository-র hook-গুলো কোনো জিজ্ঞাসা ছাড়াই চলে। তাই কোনো script চালানোর আগে তার .claude/ ফাইলগুলো পর্যালোচনা করুন, অথবা --settings '{"disableAllHooks": true}' দিয়ে চালান।
hook সম্পূর্ণ tool input দেখতে পায়। একটি audit hook যা tool_input লগ করে, তা প্রতিটি command-এর প্রতিটি argument লগে লিখে রাখে, যার মধ্যে command line-এ থাকা যেকোনো token-ও অন্তর্ভুক্ত থাকতে পারে। সেই লগটিরও গোপন তথ্যের মতোই সুরক্ষা প্রয়োজন, যা AI এজেন্টের নাগালের বাইরে গোপন তথ্য রাখা-র মতো বৃহত্তর সমস্যার একটি অংশ।
hook মডেলের context-এ লিখতে পারে। একটি সফল SessionStart বা UserPromptSubmit hook থেকে আসা plain-text stdout কথোপকথনে যুক্ত হয়। যে hook বাইরের কোনো উৎস, issue tracker বা log file থেকে text pipe করে, তা মডেলের কাছে এমনভাবে অবিশ্বস্ত text তুলে দেয় যেন আপনি নিজেই তা টাইপ করেছেন। যে hook একই VPS-এ অন্য Claude Code session থেকে কোনো নোট forward করে, সেটিও একই কাজ করে; এবং একটি এজেন্টের আউটপুট issue tracker-এর চেয়ে বেশি বিশ্বাসযোগ্য নয়। সেই stdout-কে আউটপুট হিসেবে নয়, বরং ইনপুট হিসেবে বিবেচনা করুন।
প্রাধিকার বা Privilege-ই হলো আসল নিয়ন্ত্রণ। এজেন্টকে শুধুমাত্র প্রয়োজনীয় sudo rules সহ একটি নির্দিষ্ট unprivileged ব্যবহারকারীর অধীনে চালান। একটি PreToolUse deny থাকা ভালো, তবে এটি মূলত একটি best effort ব্যবস্থা: reference-এ if filter-এর ক্ষেত্রেও একই কথা বলা হয়েছে এবং কঠিন কোনো deny-র প্রয়োজন হলে permission system ব্যবহার করতে বলা হয়েছে। permission rules এবং যে অ্যাকাউন্টের অধীনে process-টি চলছে, সেগুলোই চাপের মুখে টিকে থাকে।
একটি বৈশিষ্ট্য সব permission mode-এই কার্যকর থাকে। PreToolUse hook-গুলো সব permission mode-এ চেক করার আগেই কার্যকর হয়, তাই deny রিটার্ন করা একটি hook bypassPermissions-এর অধীনেও tool-টিকে ব্লক করতে পারে। hook-গুলো permission rules যা অনুমতি দেয় তাকে আরও কঠোর করতে পারে। কিন্তু তারা সেগুলোকে শিথিল করতে পারে না। এর ব্যতিক্রম হলো mod। কোনো managed settings এবং managed-mcp.json ফাইল নেই এমন মেশিনে, এবং এমন session-এ যা Team বা Enterprise plan-এর সাথে /login-এর মাধ্যমে sign in করা নেই, সেখানে ইনস্টল করা একটি mod যা tool.check হ্যান্ডেল করে, তা আপনার PreToolUse hook দ্বারা ব্লক করা call-টিকে অনুমোদন করতে পারে। managed settings, একটি managed-mcp.json ফাইল, অথবা session-এর credential হিসেবে Team বা Enterprise /login থাকলে, একটি PreToolUse hook দ্বারা ব্লক করা call ডিফল্টভাবেই ব্লক থাকে, তা hook-টি যে settings file থেকেই আসুক না কেন। API key বা দীর্ঘস্থায়ী CLAUDE_CODE_OAUTH_TOKEN-এর মাধ্যমে চলা session, যা অনেক সার্ভারে ব্যবহৃত হয়, তা login সংরক্ষিত থাকলেও sign in করা নেই বলে গণ্য হয়। সার্ভারে কোনো mod ইনস্টল করার আগে দেখে নিন Claude Code mod কী কী পরিবর্তন করতে পারে।
আমার hook কেন চালু হচ্ছে না?
এটি ধারাবাহিকভাবে পরীক্ষা করুন। প্রতিটি ধাপে আপনি যে লক্ষণটি বাস্তবে দেখতে পাবেন, সেটি উল্লেখ করা হয়েছে।
/hooksচালান এবং প্রত্যাশিত event-এর অধীনে hook-টি দেখা যাচ্ছে কি না পরীক্ষা করুন। মেনুতে hook না থাকলে সাধারণত settings file-এ JSON syntax error থাকে, কারণ trailing comma ও comment অনুমোদিত নয়। ফাইলটি উপরের ছয়টি location-এর কোনো একটিতেও না থাকতে পারে।- Matcher-কে tool name-এর সঙ্গে হুবহু তুলনা করুন। Matcher case-sensitive, তাই
"bash"কখনোBashtool-এর সঙ্গে মেলে না। - উপরের example 1-এর মতো sample input দিয়ে script-টি হাতে চালান। প্রত্যাশার সঙ্গে না মেলা exit code আপনার script-এর bug নির্দেশ করে। stdout-ও পরীক্ষা করুন, কারণ valid JSON হলেও
PreToolUse-এর মতো event-এ একটি decision দেওয়া যেতে পারে। jq: command not foundলেখা notice-এর অর্থ হলো ওই machine-এjqঅনুপস্থিত। আপনার নিজের script-এর জন্যcommand not foundদেখা গেলে path resolve হয়নি। তাই${CLAUDE_PROJECT_DIR}অথবা একটি absolute path ব্যবহার করুন। Script একেবারেই চালু না হলে সেটি executable না হওয়ার সম্ভাবনা বেশি।- Hook valid JSON print করে, কিন্তু কোনো ফল দেখা যায় না। macOS ও Linux-এ shell-form hook non-interactive shell-এ
sh -c-এর মাধ্যমে চলে। তবে কিছু setup এখনও আপনার profile source করে, যেমনBASH_ENV-এ~/.bashrcনির্দেশ করা থাকলে। সেই profile banner print করলে banner-টি আপনার JSON-এর আগে যুক্ত হয়। ফলে stdout আর{দিয়ে শুরু হয় না। Claude Code পুরো output-টিকে plain text হিসেবে পড়ে এবং decision উপেক্ষা করে। Hook exit 0 হওয়ায় transcript-এ কোনো error দেখা যায় না। অধিকাংশ event-এ ওই text শুধু debug log-এ যায়। তবেUserPromptSubmit,UserPromptExpansion,SessionStartএবংPostModelSwitch-এর ক্ষেত্রে banner-সহ text model-এর context-এ যোগ হয়। আপনার profile-এ থাকা যেকোনোechoএমনভাবে wrap করুন, যাতে তা শুধু interactive shell-এ চলে। - এখনও সমস্যা থাকলে
claude --debug-file /tmp/claude.logদিয়ে session শুরু করুন এবং দ্বিতীয় terminal-এtail -f /tmp/claude.logচালান। Debug log-এ কোন hook match করেছে, প্রতিটি hook কী exit code ফেরত দিয়েছে এবং stdout ও stderr-এ কী লিখেছে—সবই রেকর্ড থাকে।
FAQ
Claude Code hook এবং CLAUDE.md instruction-এর মধ্যে পার্থক্য কী?
একটি CLAUDE.md instruction হলো model-এর context-এর অংশের text। তাই এটি conversation এবং বর্তমান request-এর সঙ্গে attention-এর জন্য প্রতিযোগিতা করে, এবং model এগুলোর তুলনায় instruction-এর গুরুত্ব নির্ধারণ করতে পারে। অন্যদিকে, hook হলো একটি shell command, যা Claude Code তার lifecycle-এর নির্দিষ্ট পর্যায়ে চালায়। তাই model কী সিদ্ধান্ত নিয়েছে তা নির্বিশেষে event ঘটলেই এটি execute হয়। কোনো preference-এর জন্য instruction ব্যবহার করুন। যে step সবসময় ঘটতেই হবে বা যে action কখনোই ঘটতে পারবে না, তার জন্য hook ব্যবহার করুন।
Claude Code-কে একটি নির্দিষ্ট shell command চালানো থেকে কীভাবে আটকাব?
একটি PreToolUse hook নিবন্ধন করুন, যেখানে Bash matcher ব্যবহার করে .tool_input.command থেকে command পড়া হবে, stderr-এ একটি কারণ লেখা হবে এবং exit code 2 দেওয়া হবে। Claude Code call বাতিল করে এবং model-কে আপনার দেওয়া কারণ দেখায়। এটি permission-mode check-এর আগেই ঘটে, তাই bypassPermissions mode-এও deny কার্যকর থাকে। Command string-এর pattern matching একটি guardrail, security boundary নয়। কারণ একই command এমনভাবে লেখা যেতে পারে, যা pattern ধরতে পারে না। তাই এর সঙ্গে permission rules এবং একটি unprivileged account ব্যবহার করুন।
আমার hook valid JSON প্রিন্ট করে, কিন্তু কিছুই ঘটে না। কেন?
আপনার shell profile-এ JSON-এর আগে কোনো text প্রিন্ট হচ্ছে কি না পরীক্ষা করুন। macOS এবং Linux-এ args field ছাড়া hook sh -c-এর মাধ্যমে চলে। BASH_ENV-এর মতো setup-এ, যা এখনও আপনার profile source করে এবং ~/.bashrc-এর দিকে নির্দেশ করে, profile-এ প্রিন্ট হওয়া banner আপনার JSON-এর আগে stdout-এ চলে আসে। ফলে output আর { দিয়ে শুরু হয় না। Claude Code পুরো output-কে plain text হিসেবে বিবেচনা করে এবং decision উপেক্ষা করে। Hook exit 0 দেওয়ায় transcript-এ কোনো error-ও দেখা যায় না। Profile-এর যেকোনো echo-কে interactive-shell test দিয়ে guard করুন। এরপর claude --debug-file /tmp/claude.log থেকে debug log পড়ে fix কার্যকর হয়েছে কি না নিশ্চিত করুন।
Shared server-এ Claude Code hook চালানো কি নিরাপদ?
Claude Code যে user চালু করেছে, hook সেই user হিসেবেই চলে এবং ওই user-এর file permission ব্যবহার করে। তাই ওই account যা করতে পারে, hook-ও তা করতে পারে। ঝুঁকির বেশিরভাগ অংশ সামলাতে দুটি অভ্যাস যথেষ্ট: agent-কে একটি dedicated unprivileged account হিসেবে চালান এবং সীমিত sudo policy ব্যবহার করুন। কোনো repository-এর workspace trust dialog গ্রহণ করার আগে বা সেখানে claude -p চালানোর আগে তার hooks block পড়ুন। কারণ project hook-গুলো .claude/settings.json-এর ভেতরে থাকে এবং -p mode কখনো ওই dialog দেখায় না। Hook নিষ্ক্রিয় করতে আপনার settings file-এ "disableAllHooks": true সেট করুন। তবে managed hook-এর ক্ষেত্রে setting-টি managed level-এ প্রয়োজন হতে পারে। কোনো project setting-এর false মান user setting-এর true মানকে override করতে পারে।