آموزش کامل هوکهای Claude Code و نحوه عملکرد آنها
در این راهنما بررسی میکنیم که چگونه هوکهای Claude Code مستقل از تصمیم مدل اجرا میشوند. نحوه استفاده از exit code 2 در PreToolUse برای لغو ابزارها و نکات امنیتی آن را بیاموزید.
هوک Claude Code چیست
هوکهای Claude Code دستورات shell هستند که Claude Code آنها را در نقاط مشخصی از چرخه حیات خود بهصورت خودکار اجرا میکند. این تمام تفاوت بین یک هوک و یک فایل قوانین است. دستورالعمل موجود در CLAUDE.md یک توصیه است و مدل آن را در کنار سایر موارد موجود در context خود میسنجد. اما هوک یک کد است و فارغ از موافقت یا مخالفت مدل، اجرا میشود. اگر agent شما مدام فرمتکنندهای را که دو بار به آن گفتهاید نادیده میگیرد، نیازی به دستورالعمل سختگیرانهتر ندارید؛ شما به یک هوک نیاز دارید.
مکانیسم آن ساده است. شما یک دستور را در یک فایل تنظیمات تحت یک نام رویداد ثبت میکنید. هنگامی که آن رویداد رخ میدهد، Claude Code دستور شما را اجرا کرده و دادههای رویداد را به صورت JSON (نمادگذاری شیء جاوااسکریپت) به ورودی استاندارد (stdin) آن میفرستد. دستور شما دادهها را میخواند، کار خود را انجام میدهد و با یک وضعیت خروج (exit status) پاسخ میدهد. خروج با کد 2 از یک هوک PreToolUse، فراخوانی ابزار را پیش از اجرا لغو میکند. هر آنچه اسکریپت شما در خروجی خطای استاندارد (stderr) بنویسد، به عنوان دلیل به مدل بازگردانده میشود، مگر اینکه هوک حاوی یک JSON با تصمیم مسدودکننده (blocking decision) باشد که در آن صورت دلیلِ آن اولویت دارد.
نام رویدادها و نام فیلدها در اینجا از مرجع هوکهای Claude Code گرفته شدهاند که در تاریخ 12 نوامبر 2026 بررسی شده است. این حوزه بهسرعت تغییر میکند، بنابراین پیش از کپی کردن JSON از هر پست وبلاگی (از جمله همین پست)، مرجع مربوط به نسخه خود را بررسی کنید. نسخه خود را با claude --version چاپ کنید.
محل قرارگیری پیکربندی hook
hook یک بلوک JSON در فایل settings است. شش محل میتوانند چنین بلوکی را در خود داشته باشند و scope فایل، scope همان hook است.
~/.claude/settings.json: همه پروژههای روی سیستم شما، و فقط برای خود شما..claude/settings.json: یک پروژه که در repository commit میشود؛ بنابراین هرکس آن را clone کند، hook را دریافت میکند..claude/settings.local.json: یک پروژه، فقط روی سیستم شما.- تنظیمات policy مدیریتشده: در سراسر سازمان و توسط administrator تعیین میشود.
hooks/hooks.jsonداخل یک plugin؛ تا زمانی که آن plugin فعال باشد، hook نیز فعال میماند.- frontmatter مربوط به skill یا subagent. hookهای یک skill پس از invoke شدن skill تا پایان session فعال میمانند و hookهای یک subagent تا زمانی که آن subagent در حال اجراست فعال هستند.
ورودیهای hook در این فایلها با یکدیگر merge میشوند و یکدیگر را override نمیکنند. فایل settings پروژه، hookهای خود را به hookهای موجود در user settings اضافه میکند و آنها را جایگزین نمیکند؛ بنابراین یک event میتواند چند hook را از چند فایل در خود داشته باشد. تنظیم "disableAllHooks": true آنها را غیرفعال میکند، با یک استثنا: hookهای موجود در تنظیمات policy مدیریتشده به اجرا ادامه میدهند، مگر اینکه آن تنظیم در managed settings نیز اعمال شود.
برای فهرستکردن همه hookهای ثبتشده در session، آنها را بر اساس event و همراه با فایل مبدأ و matcher مربوط به هرکدام، /hooks را اجرا کنید. این menu فقط قابل خواندن است؛ بنابراین برای تغییر یک hook باید فایل settings را ویرایش کنید. file watcher معمولاً تغییر را بدون restart شناسایی میکند.
رویدادهای هوک در Claude Code کدامند
مرجع هوکها شامل 33 رویداد است که از SessionStart تا SessionEnd را در بر میگیرد و شامل فشردهسازی (compaction)، زیرعاملها (subagents)، درختهای کاری (worktrees) و فایلهای پیکربندی میشود. در کارهای سروری از تعداد محدودی از آنها استفاده میشود.
PreToolUse: پیش از اجرای یک فراخوانی ابزار، به جزEndConversation. این تنها هوکی است که میتواند عملیات را مسدود کند.PostToolUse: پس از موفقیتآمیز بودن یک فراخوانی ابزار، به جزEndConversation. رویدادPostToolUseFailureدر زمان شکست فراخوانی اجرا میشود، بنابراین هوکی که باید تمام نتایج را مشاهده کند، به هر دو نیاز دارد.PermissionRequest: زمانی که یک فراخوانی ابزار نیاز به تصمیمگیری برای مجوز دارد؛ یعنی لحظهای که اعلان تأیید (approval prompt) ظاهر میشود.UserPromptSubmit: زمانی که یک پرامپت را ارسال میکنید، پیش از آنکه Claude آن را پردازش کند. خروجی استاندارد (stdout) متنی از یک هوک موفق به کانتکست مدل اضافه میشود.SessionStartوSessionEnd: در هر دو انتهای یک نشست (session). رویدادSessionStartهمچنین پس از فشردهسازی و تحت مقدار تطبیقدهنده (matcher)compactاجرا میشود.Stop: زمانی که پاسخدهی Claude به پایان میرسد. این رویداد یک بار در هر نوبت (turn) اجرا میشود، نه یک بار در هر وظیفه (task) کاملشده.
در رویدادهایی که از تطبیقدهندهها پشتیبانی میکنند، یک گروه میتواند دارای یک matcher باشد که تعیین میکند کدام رخدادها هوک را اجرا کنند. در رویدادهای ابزار، این فیلتر بر اساس نام ابزار عمل میکند؛ بنابراین "Edit|Write" فقط در زمان ویرایش فایل اجرا میشود و نه هیچ مورد دیگر. تطبیقدهندهها به حروف بزرگ و کوچک حساس هستند. یک تطبیقدهنده خالی روی تمام رخدادها اجرا میشود. ابزارهای یک سرور MCP (پروتکل کانتکست مدل) با نام mcp__<server>__<tool> شناخته میشوند، بنابراین یک تطبیقدهنده به صورت "mcp__github__.*" ابزارهای یک سرور خاص را هدف قرار داده و سایرین را نادیده میگیرد.
هوکهای Stop دارای یک تله هستند که پیش از نوشتن هوک باید از آن آگاه باشید. یک هوک Stop که عملیات را مسدود میکند، مدل را دوباره به کار میفرستد. بهطور پیشفرض، Claude Code پس از 8 ادامه (continuation) متوالی، بلوک بعدی را نادیده میگیرد و این شمارش هر زمان که Claude ابزاری را فراخوانی کند، بازنشانی میشود. فیلد stop_hook_active را از ورودی هوک بخوانید و در صورتی که true بود، با کد 0 خارج شوید؛ در غیر این صورت، هوک شما ممکن است مدام Claude را به کار بازگرداند.
آنچه یک هوک از طریق stdin دریافت میکند
هنگامی که Claude قصد اجرای npm test را دارد، یک هوک PreToolUse در Bash موارد زیر را از طریق stdin میخواند:
{
"session_id": "abc123",
"cwd": "/home/deploy/myproject",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test"
}
}فیلدهای ورودی رایج شامل session_id، cwd، transcript_path و hook_event_name هستند؛ permission_mode در هر رویداد ارسال نمیشود. رویدادهای ابزار، فیلدهای tool_name، tool_input و tool_use_id را اضافه میکنند. سایر رویدادها فیلدهای خاص خود را حمل میکنند: UserPromptSubmit متن prompt را دریافت میکند و SessionStart یک source از startup، resume، clear، compact یا fork را میگیرد.
jq روش معمول برای خواندن این دادهها در یک اسکریپت shell است و یک image سرور حداقلی آن را ندارد. ابتدا آن را با sudo apt install -y jq در Ubuntu و Debian نصب کنید.
تأثیر وضعیت خروج (exit status) بر فراخوانی ابزار در حال اجرا
سه نتیجه ممکن وجود دارد.
- خروج با کد 0 به معنای موفقیت است و هر فیلد تصمیمگیری معتبر در JSON همچنان اعمال میشود، از جمله مسدودسازی یا رد درخواست. در
PreToolUse، خروج با کد 0 بدون ارائه تصمیم به معنای تأیید نیست و جریان عادی مجوزها همچنان اجرا میشود. درUserPromptSubmit،UserPromptExpansion،SessionStartوPostModelSwitch، خروجی متنی ساده (stdout) به کانتکست مدل اضافه میشود. در اکثر رویدادهای دیگر، stdout فقط به لاگ دیباگ ارسال میشود. - خروج با کد 2 عملیات را در رویدادهایی که قابل مسدودسازی هستند (از جمله
PreToolUse) متوقف میکند و stderr به پیامی تبدیل میشود که همراه با مسدودسازی ارسال میگردد، مگر اینکه خروجی JSON حاوی یک تصمیم مسدودکننده باشد که دلیل آن اولویت دارد. اینکه چه کسی آن پیام را میخواند به نوع رویداد بستگی دارد. درPreToolUseوStop، مدل آن را به عنوان دلیل میبیند. درUserPromptSubmitوPreModelSwitch، پیام به شما نمایش داده میشود و به کانتکست مدل اضافه نمیشود. درPostToolUseوPostToolUseFailureکه قابل مسدودسازی نیستند، مسدودسازی نادیده گرفته میشود، اگرچه stderr همچنان به عنوان بازخورد به مدل میرسد. در اکثر رویدادهای دیگر که قابل مسدودسازی نیستند، stderr فقط به شما نمایش داده شده یا نادیده گرفته میشود. درStop،SubagentStop،TaskCompletedو هوکUserPromptSubmitیک پلاگین، خروج با کد 2 همراه با stdout خالی و خطای فایل یافت نشد در stderr، به عنوان یک خطای غیرمسدودکننده در نظر گرفته میشود. - هر کد خروج دیگر با stdout متنی ساده یا خالی، معمولاً یک خطای غیرمسدودکننده است. رونوشت (transcript) یک اعلان خطای هوک را نشان میدهد که حاوی اولین خط stderr پس از متن
Failed with non-blocking status code:است. JSON معتبر همچنان میتواند نتیجه را در رویدادهایی مانندPreToolUseتعیین کند، مگر اینکه شکست هوک باعث مسدود شدن عملیات شود.WorktreeCreateدر هر خروج غیر صفر شکست میخورد وWorktreeRemoveدر صورت خروج غیر صفر، اگر دایرکتوری پس از آن همچنان وجود داشته باشد، شکست میخورد.
برای هر چیزی فراتر از مسدود کردن یا سکوت، از خروج با کد 0 استفاده کنید و یک شیء JSON را در stdout چاپ کنید. یک هوک PreToolUse با permissionDecision تصمیمگیری میکند:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database drops go through a migration, not through the agent."
}
}"allow" در جایی که قوانین مجوز و الزامات تأیید ابزار اجازه میدهند، از پرامپت تعاملی عبور میکند، "deny" فراخوانی را لغو کرده و دلیل آن را به مدل میفرستد، و "ask" درخواست تأیید میکند. برای هر هوک یک سبک انتخاب کنید. ترکیب خروج با کد 2 با یک تصمیم JSON در stdout، مسدودسازی را حفظ میکند، حتی اگر JSON مقدار "allow" را اعلام کند.
هنگامی که چندین هوک با یک رویداد مطابقت دارند، آنها به صورت موازی اجرا میشوند، با این محدودیت که حداکثر دوازده هوک پرامپت و عامل (agent) میتوانند همزمان اجرا شوند. یک deny از یک هوک، هوکهای همرده خود را متوقف نمیکند، بنابراین یک هوک لاگگیری همچنان خط خود را مینویسد در حالی که یک هوک محافظ (guardrail) همان فراخوانی را رد میکند. برای PreToolUse، Claude Code پاسخها را ادغام کرده و محدودکنندهترین آنها را به ترتیبِ رد کردن، تعویق، پرسش و تأیید حفظ میکند.
مثال 1: مسدود کردن یک دستور مخرب پیش از اجرا
این فایل را با نام .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آن را قابلاجرا کنید و سپس در PreToolUse در مسیر .claude/settings.json ثبت نمایید:
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 تنظیم نشده باشد، اجازه عبور میدهد (fail open). در ویندوز بدون Git Bash، یک هوک با فرم shell که در PreToolUse یا PermissionRequest شکست بخورد، میتواند بهجای آن، فراخوانی ابزار را مسدود کند:
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
| .claude/hooks/block-destructive.sh
echo $?شما باید خط Blocked by policy: را در stderr و کد خروج 2 را مشاهده کنید. یک دستور بیخطر مانند ls -la را به آن بدهید؛ در این حالت نباید هیچ خروجیای ببینید و کد خروج باید 0 باشد. در یک نشست، فراخوانی مسدودشده در رونوشت (transcript) به همراه پیام شما به عنوان دلیل ظاهر میشود و مدل آن پیام را خوانده و خود را تطبیق میدهد.
یک ویژگی باعث میشود این کار ارزشمند باشد: هوکهای PreToolUse پیش از بررسی حالت دسترسی (permission-mode) و در تمامی حالتهای دسترسی اجرا میشوند، بنابراین مسدودسازی حتی در حالت bypassPermissions نیز اعمال میشود. همین موضوع باعث میشود یک هوک در کنار حالت خودکار Claude Code و تنظیمات دسترسی آن مفید باشد؛ جایی که پرامپتها محدود شدهاند اما هوک همچنان اجرا میشود.
در مورد ماهیت این ابزار صادق باشید. تطبیق الگو (Pattern matching) روی رشته دستور، یک حفاظ در برابر بیدقتی عامل (agent) است و مرزی در برابر هوشمندی عامل محسوب نمیشود؛ زیرا همان دستور میتواند به شکلی نوشته شود که grep شما هرگز آن را نبیند. قوانین سختگیرانه باید در سیستم دسترسی و در حسابی که پردازش تحت آن اجرا میشود، اعمال گردند.
مثال 2: فرمت و lint کردن پس از هر ویرایش
یک PostToolUse با یک matcher از نوع Edit|Write، پس از موفقیت هر یک از آن ابزارهای ویرایش فایل اجرا میشود. این را به عنوان .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 بخواهید یک تابع با تورفتگی (indentation) نامناسب به یک فایل Python اضافه کند، سپس فایل را باز کنید. فایل بهصورت فرمتشده بازمیگردد. این نشاندهنده اجرای hook است، زیرا یک hook موفق هیچ خروجی در گفتگو نمایش نمیدهد.
دستور exit 2 در اینجا هیچ تغییری را لغو نمیکند. PostToolUse پس از اجرای ابزار فعال میشود، بنابراین ویرایش در هر صورت روی دیسک اعمال شده است. مزیت استفاده از exit 2 این است که خروجی ruff check به عنوان بازخورد به مدل ارسال میشود، بنابراین مدل به جای ادامه کار، خطایی را که بهتازگی ایجاد کرده است اصلاح میکند. این تفاوت بین خطای lint که در زمان commit پیدا میکنید و خطایی است که عامل (agent) در همان نوبت آن را تعمیر میکند.
دو محدودیت matcher در اینجا اهمیت دارند. Edit|Write فایلهای تغییریافته توسط دستورات shell را نمیبیند و Claude آنقدر از طریق Bash فایلها را مینویسد که این شکاف واقعی باشد. برای پوشش در هر فراخوانی، Bash را نیز match کنید و اسکریپت را طوری تنظیم کنید که فایلهای تغییریافته را با git status --porcelain لیست کند. برای پوشش یکبار در هر نوبت، اسکن را در یک hook از نوع Stop قرار دهید.
مثال 3: ثبت لاگ تمام فراخوانیهای ابزار برای بازرسی
یک matcher خالی در PostToolUse برای هر فراخوانی موفق ابزار، به جز EndConversation، اجرا میشود. ارسال رکورد به journal سیستم بهجای یک فایل در دایرکتوری home، آن را از دسترس shell خودِ agent خارج نمیکند: دسترسی به این رکوردها به مجوزهای حساب کاربری بستگی دارد. کاربران میتوانند journalهای خصوصی خود را بخوانند و کاربر root به همراه اعضای گروههای systemd-journal، adm یا wheel میتوانند تمام فایلهای journal را مطالعه کنند:
{
"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 بخوانید. با داشتن مجوز خواندن رکوردها، باید به ازای هر فراخوانی موفق ابزار (به جز EndConversation)، یک خط JSON مشاهده کنید که جدیدترین آنها در انتها قرار دارد. اگر چیزی نمایش داده نشد، دسترسی به journal و همچنین اجرای hook را بررسی کنید؛ بخش عیبیابی در ادامه، hook را پوشش میدهد.
همین بلوک را در زیر PostToolUseFailure اضافه کنید تا فراخوانیهای ناموفق نیز ثبت شوند، زیرا PostToolUse فقط در صورت موفقیت اجرا میشود و معمولاً دستورات ناموفق هستند که اهمیت دارند. دلیل استفاده از logger بهجای اضافه کردن (append) به یک فایل در دایرکتوری home، مالکیت فایل است: یک hook با همان کاربری اجرا میشود که shell مربوط به agent با آن اجرا شده است؛ بنابراین کاربر میتواند هر فایلی را که امکان اضافه کردن به آن را دارد، truncate (پاکسازی) نیز بکند. journal توسط systemd-journald نوشته میشود؛ محافظت از آن در برابر حذف، همچنان به سطح دسترسیهای حساب کاربری agent بستگی دارد.
مدت زمان اجرای یک هوک
دادههای پشت این نمودار
[
{
"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
}
]یک هوک دستوری بهصورت پیشفرض 600 ثانیه، یعنی ده دقیقه زمان دارد. برخی رویدادها این زمان را بهشدت کاهش میدهند. هوکهای SessionEnd در مجموع یک بودجه زمانی 1.5 ثانیهای بین همه خود دارند، بنابراین پاکسازی پایان نشست (end-of-session) باید سریع انجام شود؛ هرچند تنظیم یک timeout طولانیتر برای یک هوک در فایلهای تنظیمات، این بودجه مشترک را تا سقف 60 ثانیه افزایش میدهد.
یک دستور همگام (synchronous)، هوک HTTP یا ابزار MCP که به محدودیت زمانی خود برسد، لغو شده و معمولاً تصمیمی صادر نمیکند؛ در مورد PreModelSwitch، اتمام زمان باعث مسدود شدن سوئیچ میشود. برای یک guardrail از نوع PreToolUse، اتمام زمان معمولاً اجازه میدهد فراخوانی ابزار در جریان عادی مجوزها ادامه یابد (با استثنای ویندوزی که در بالا ذکر شد، زمانی که onFailure تنظیم نشده باشد). به همین دلیل، اسکریپتهای guardrail را کوچک نگه دارید. از نسخه 2.1.295 به بعد، میتوانید این رفتار پیشفرض را در هوکهای command یا http با استفاده از "onFailure": "block" معکوس کنید؛ این کار باعث میشود اتمام زمان، کرش کردن یا خروج با کد غیرمنتظره منجر به مسدودسازی شود، هرچند این تنظیم روی هوکهای Stop، SubagentStop، TaskCompleted، TeammateIdle یا هوکهای دستوری پسزمینه تأثیری ندارد. برای کارهای کندی که کسی منتظر آنها نیست، مانند ارسال لاگ به یک مقصد، "async": true را تنظیم کنید تا هوک در پسزمینه اجرا شود و فراخوانی ابزار را معطل نکند.
هوکها، فایلهای قوانین، مهارتها و سرورهای MCP
چهار مورد وجود دارند که اغلب با یکدیگر اشتباه گرفته میشوند، زیرا همگی عملکرد عامل (agent) را تغییر میدهند. تنها یکی از آنها از حالت پیشنهاد خارج میشود.
یک فایل قوانین (CLAUDE.md، یا فایلی در مسیر .claude/rules/) متنی است که در کانتکست مدل بارگذاری میشود. این فایل رفتار را شکل میدهد اما هیچچیز را اجبار نمیکند. در مواجهه با یک گفتگوی طولانی، یک diff بزرگ و یک درخواست جدید از کاربر، ممکن است یک خط از آن نادیده گرفته شود. این همان مکانیسم معمولی است که باعث نادیده گرفتن دستورالعملهای نوشتهشده توسط عاملها میشود.
یک مهارت (skill)، پوشهای از دستورالعملها و اسکریپتهاست که مدل در صورت تشخیص مرتبط بودن، آن را بارگذاری میکند. این قضاوت، هدف اصلی یک مهارت است و در عین حال محدودیت آن نیز محسوب میشود: تصمیم نهایی همچنان با مدل است. شما میتوانید هر دو جنبه را در مهارتی مانند Ponytail، که عامل را به سمت کوچکترین تغییرِ کارآمد سوق میدهد مشاهده کنید؛ زیرا این مهارت نحوهٔ رویکرد به کل یک وظیفه را به شکلی شکل میدهد که هیچ هوکی قادر به آن نیست، و تنها زمانی عمل میکند که مدل تصمیم به بارگذاری آن بگیرد.
یک سرور MCP (پروتکل کانتکست مدل) ابزارهای جدیدی برای فراخوانی در اختیار مدل قرار میدهد. این کار دامنهٔ دسترسی عامل را گسترش میدهد. این پروتکل عامل را مجبور به استفاده از هیچچیز نمیکند و یک پردازش جداگانه است که باید آن را مدیریت کنید، که خود وظیفهای مستقل است: به اجرای سرورهای MCP روی یک VPS مراجعه کنید.
هوک (hook) تنها مورد از این چهار مورد است که بدون انتخاب مدل اجرا میشود. از فایل قوانین برای اولویتها و از مهارت برای رویهای که مدل باید هنگام اعمال آن دنبال کند، استفاده کنید. از هوک برای مرحلهای استفاده کنید که باید هر بار اتفاق بیفتد، یا برای کاری که هرگز نباید رخ دهد. مقایسهٔ عمیقتر، از جمله اینکه چه زمانی یک مهارت بر فایل قوانین برتری دارد، در مقایسه مهارتها، MCP و فایلهای قوانین آمده است.
پلاگین (plugin) بیش از آنکه مکانیسم پنجم باشد، یک بستهبندی است. پلاگینها هوکها را همراه با مهارتها در یک واحد قابل نصب ترکیب میکنند؛ این همان روشی است که یک تیم، یک چارچوب حفاظتی (guardrail) یکسان را روی تمام ماشینها توزیع میکند: به نحوه عملکرد پلاگینهای Claude Code مراجعه کنید.
تصمیم امنیتی روی یک VPS اشتراکی
هوک کدی است که توسط agent فعال میشود و با کاربری که Claude Code را اجرا کرده است، اجرا میگردد. این هوک مجوزهای فایل و محیط (environment) همان کاربر را به ارث میبرد. روی یک لپتاپ، این یک مسئله مربوط به گردش کار است. اما روی یک VPS که agent در آن بدون نظارت اجرا میشود، این یک مسئله امنیتی با چهار بخش کاربردی است.
هوک موجود در یک مخزن (repository)، کدی است که شما ننوشتهاید. .claude/settings.json commit میشود، بنابراین clone کردن یک مخزن و شروع یک session در داخل آن میتواند هوکهایی را که همراه مخزن بودهاند، ثبت کند. در یک session تعاملی، Claude Code هوکهای پروژه را پشت دیالوگ اعتماد به فضای کاری (workspace trust) برای آن پوشه محدود میکند؛ به این معنی که پذیرش اعتماد، لحظهای است که تصمیم میگیرید آنها را اجرا کنید. ابتدا بلوک hooks را بخوانید. یک session از نوع claude -p یا SDK، که معمولاً نحوه اجرای یک agent بدون نظارت است، هرگز آن دیالوگ را نشان نمیدهد و پوشه را قابلاعتماد تلقی میکند، بنابراین هوکهای مخزن بدون پرسش اجرا میشوند. پیش از اسکریپتنویسی علیه آن، فایلهای .claude/ آن را بررسی کنید یا با --settings '{"disableAllHooks": true}' اجرا کنید.
هوک ورودی کامل ابزار را میبیند. یک هوک حسابرسی (audit hook) که tool_input را لاگ میکند، تمام آرگومانهای هر دستور را در یک لاگ مینویسد، از جمله هر توکنی که ممکن است روی خط فرمان قرار گرفته باشد. آن لاگ سپس به همان محافظتی نیاز دارد که secret به آن نیاز دارد، که بخشی از مشکل گستردهتر دور نگه داشتن secretها از دسترس agentهای هوش مصنوعی است.
هوک میتواند در context مدل بنویسد. خروجی استاندارد (stdout) متنی از یک هوک موفق SessionStart یا UserPromptSubmit به گفتگو اضافه میشود. هوکی که متن را از بیرون (یک سیستم ردیابی مشکلات یا یک فایل لاگ) به داخل pipe میکند، در واقع متن غیرقابلاعتماد را طوری به مدل میدهد که انگار خودتان آن را تایپ کردهاید. هوکی که یادداشتی را از یک session دیگر Claude Code روی همان VPS فوروارد میکند نیز همین کار را انجام میدهد و خروجی یک agent، اعتبار بیشتری نسبت به سیستم ردیابی مشکلات برای جلب اعتماد شما ندارد. با آن stdout به عنوان ورودی رفتار کنید، نه به عنوان خروجی.
امتیاز (Privilege) کنترل اصلی است. agent را به عنوان یک کاربر اختصاصی بدون امتیاز (unprivileged) با تنها sudo قوانین مورد نیاز اجرا کنید. داشتن یک deny در PreToolUse ارزشمند است، اما طراحی آن بر اساس بهترین تلاش (best effort) است: مرجع در مورد فیلتر if نیز همین را میگوید و به شما توصیه میکند که هنگام نیاز به یک deny سخت، از سیستم مجوزها استفاده کنید. قوانین مجوز و حسابی که پردازش تحت آن اجرا میشود، بخشهایی هستند که در شرایط فشار پایدار میمانند.
یک ویژگی در تمام حالتهای مجوز برقرار است. هوکهای PreToolUse پیش از بررسی حالت مجوز در هر حالت مجوزی فعال میشوند، بنابراین هوکی که deny را برمیگرداند، ابزار را حتی تحت bypassPermissions مسدود میکند. هوکها میتوانند آنچه را که قوانین مجوز اجازه میدهند، محدودتر کنند. آنها نمیتوانند آن را تسهیل کنند. استثنا یک mod است. روی دستگاهی بدون تنظیمات مدیریتشده و بدون فایل managed-mcp.json، در sessionای که از طریق /login به یک طرح Team یا Enterprise وارد نشده است، یک mod نصبشده که tool.check را مدیریت میکند، میتواند فراخوانیای را که هوک PreToolUse شما مسدود کرده است، تأیید کند. با تنظیمات مدیریتشده، یک فایل managed-mcp.json، یا یک /login از نوع Team یا Enterprise به عنوان اعتبارنامه session، فراخوانیای که یک هوک PreToolUse مسدود کرده است، بهطور پیشفرض مسدود باقی میماند، فارغ از اینکه هوک از کدام فایل تنظیمات آمده باشد. sessionای که روی یک API key یا یک CLAUDE_CODE_OAUTH_TOKEN با عمر طولانی اجرا میشود (که نحوه اجرای بسیاری از سرورهاست)، حتی در صورت ذخیره شدن login، به عنوان "وارد نشده" (not signed in) محسوب میشود. پیش از نصب mod روی سرور، بررسی کنید که modهای Claude Code چه چیزی را میتوانند تغییر دهند.
چرا هوک (hook) من اجرا نمیشود؟
این مراحل را به ترتیب دنبال کنید. هر مرحله نشاندهنده علامتی است که در عمل مشاهده خواهید کرد.
- دستور
/hooksرا اجرا کنید و بررسی کنید که آیا هوک در زیر رویداد مورد انتظار شما ظاهر میشود یا خیر. اگر هوکی در منو وجود ندارد، معمولاً به این معنی است که فایل تنظیمات دارای خطای نحوی JSON است، زیرا استفاده از کامای اضافی (trailing comma) و کامنت در آن مجاز نیست، یا اینکه فایل در یکی از شش مسیر ذکر شده در بالا قرار ندارد. - تطبیقدهنده (matcher) را دقیقاً با نام ابزار مقایسه کنید. تطبیقدهندهها به حروف بزرگ و کوچک حساس هستند، بنابراین
"bash"هرگز با ابزارBashمطابقت نخواهد داشت. - اسکریپت را بهصورت دستی و با ورودی نمونه، همانطور که در مثال 1 بالا آمده است، اجرا کنید. کد خروجی (exit code) غیرمنتظره، نشاندهنده وجود باگ در اسکریپت شماست؛ خروجی استاندارد (stdout) آن را نیز بررسی کنید، زیرا JSON معتبر همچنان میتواند تصمیمی برای رویدادهایی مانند
PreToolUseارائه دهد. - مشاهده اعلان
jq: command not foundبه این معنی است کهjqروی آن ماشین وجود ندارد. خطایcommand not foundبرای اسکریپت شخصی شما به این معنی است که مسیر پیدا نشده است، بنابراین از${CLAUDE_PROJECT_DIR}یا یک مسیر مطلق (absolute path) استفاده کنید. اگر اسکریپت اصلاً اجرا نمیشود، احتمالاً مجوز اجرای آن تنظیم نشده است. - هوک JSON معتبر چاپ میکند اما اتفاقی نمیافتد. در macOS و Linux، هوکهای با فرمت shell از طریق
sh -cدر یک shell غیرتعاملی اجرا میشوند، اما برخی تنظیمات همچنان پروفایل شما را source میکنند، مانند زمانی کهBASH_ENVبه~/.bashrcاشاره دارد. اگر آن پروفایل بنری را چاپ کند، آن بنر به ابتدای JSON شما اضافه میشود. در نتیجه، خروجی استاندارد دیگر با{شروع نمیشود و Claude Code کل محتوا را به عنوان متن ساده میخواند و تصمیم را نادیده میگیرد. از آنجا که هوک با کد 0 خارج شده است، در گزارش (transcript) خطایی دیده نمیشود. در اکثر رویدادها، آن متن فقط به لاگ دیباگ میرود، در حالی که درUserPromptSubmit،UserPromptExpansion،SessionStartوPostModelSwitch، متن مذکور به همراه بنر به کانتکست مدل اضافه میشود. هرگونهechoرا در پروفایل خود به شکلی محدود کنید که فقط در shellهای تعاملی اجرا شود. - اگر همچنان مشکل باقی است: نشست را با
claude --debug-file /tmp/claude.logشروع کنید و در ترمینال دومtail -f /tmp/claude.logرا اجرا نمایید. لاگ دیباگ ثبت میکند که کدام هوکها مطابقت داشتهاند، هر کدام چه کد خروجی بازگرداندهاند و هر آنچه را که در stdout و stderr نوشتهاند، ضبط میکند.
FAQ
تفاوت بین hook در Claude Code و دستورالعمل در CLAUDE.md چیست؟
دستورالعمل CLAUDE.md متنی در context مدل است، بنابراین برای جلب توجه مدل با گفتگو و درخواست فعلی رقابت میکند و مدل میتواند آن را در برابر آنها بسنجد. یک hook یک دستور shell است که Claude Code آن را در نقطه ثابتی از چرخه حیات خود اجرا میکند، بنابراین فارغ از تصمیم مدل، در هر بار وقوع رویداد مربوطه اجرا میشود. برای اولویتها از دستورالعمل و برای گامی که باید همیشه انجام شود یا عملی که هرگز نباید رخ دهد، از hook استفاده کنید.
چگونه از اجرای یک دستور shell خاص توسط Claude Code جلوگیری کنم؟
یک hook از نوع PreToolUse با یک matcher از نوع Bash ثبت کنید که دستور را از .tool_input.command میخواند، دلیلی را در stderr مینویسد و با کد 2 خارج میشود. Claude Code فراخوانی را لغو کرده و دلیل شما را به مدل نشان میدهد؛ این اتفاق پیش از بررسی permission-mode رخ میدهد، بنابراین این منع حتی در حالت bypassPermissions نیز معتبر است. تطبیق الگو (pattern matching) روی رشته دستور، یک ابزار حفاظتی است نه یک مرز امنیتی، زیرا همان دستور میتواند به شکلی نوشته شود که از دید الگو پنهان بماند؛ بنابراین آن را با قوانین دسترسی و یک حساب کاربری بدون امتیاز (unprivileged) پشتیبانی کنید.
hook من JSON معتبر چاپ میکند اما اتفاقی نمیافتد. چرا؟
فایل profile شل خود را برای متونی که پیش از JSON چاپ میشوند بررسی کنید. در macOS و Linux، یک hook بدون فیلد args از طریق sh -c اجرا میشود و در تنظیماتی که همچنان profile شما را source میکنند، مانند زمانی که BASH_ENV به ~/.bashrc اشاره دارد، profileای که یک بنر چاپ میکند آن را پیش از JSON شما در stdout قرار میدهد. از آنجا که خروجی دیگر با { شروع نمیشود، Claude Code تمام آن را به عنوان متن ساده در نظر گرفته و تصمیم را نادیده میگیرد؛ و چون hook با کد 0 خارج شده، transcript هیچ خطایی را نشان نمیدهد. هرگونه echo در profile خود را با یک تست interactive-shell محدود کنید، سپس اصلاح را با خواندن لاگ دیباگ از claude --debug-file /tmp/claude.log تأیید کنید.
آیا اجرای hookهای Claude Code روی یک سرور اشتراکی امن است؟
hookها با کاربری که Claude Code را شروع کرده و با مجوزهای فایل همان کاربر اجرا میشوند، بنابراین یک hook میتواند هر کاری که آن حساب قادر به انجامش است را انجام دهد. دو عادت بخش بزرگی از ریسک را پوشش میدهد: عامل (agent) را به عنوان یک حساب کاربری اختصاصی و بدون امتیاز با سیاست sudo محدود اجرا کنید، و پیش از پذیرش گفتگوی اعتماد به workspace یا اجرای claude -p در یک مخزن، بلوک hooks آن را بخوانید؛ زیرا hookهای پروژه درون .claude/settings.json قرار دارند و حالت -p هرگز آن گفتگو را نمایش نمیدهد. برای غیرفعال کردن hookها، مقدار "disableAllHooks": true را در فایل تنظیمات خود قرار دهید، مگر برای hookهای مدیریتشده که به تنظیمات در سطح مدیریت نیاز دارند؛ تنظیمات پروژه با مقدار false میتواند تنظیمات کاربر با مقدار true را نادیده بگیرد.