Claude Code Hooks: செயல்முறை மற்றும் பாதுகாப்பு விளக்கம்
Claude Code hooks எவ்வாறு செயல்படுகின்றன என்பதை அறியுங்கள். Model-ன் முடிவை மீறி இவை இயங்கும் விதம், exit code 2-ன் தாக்கம் மற்றும் பாதுகாப்பு அபாயங்கள் குறித்த விரிவான வழிகாட்டி.
Claude Code hook என்றால் என்ன
Claude Code hooks என்பது அதன் lifecycle-ல் குறிப்பிட்ட புள்ளிகளில் Claude Code தானாகவே இயக்கும் shell commands ஆகும். இதுவே hook-க்கும் rules file-க்கும் உள்ள முக்கிய வேறுபாடு. CLAUDE.md-ல் உள்ள ஒரு அறிவுரை வெறும் ஆலோசனையே; அதை அதன் context-ல் உள்ள மற்ற அனைத்தோடும் ஒப்பிட்டு model முடிவெடுக்கும். ஆனால் hook என்பது code; model ஒப்புக்கொண்டாலும் இல்லாவிட்டாலும் அது இயங்கும். நீங்கள் இருமுறை கூறியும் உங்கள் agent formatter-ஐத் தவிர்க்கிறது என்றால், அதற்கு இன்னும் கண்டிப்பான அறிவுரை தேவையில்லை. உங்களுக்கு ஒரு hook தேவை.
இதன் செயல்முறை எளிதானது. ஒரு settings file-ல் event name ஒன்றின் கீழ் நீங்கள் ஒரு command-ஐப் பதிவு செய்ய வேண்டும். அந்த event நிகழும்போது, Claude Code உங்கள் command-ஐ இயக்கி, event தரவுகளை JSON (JavaScript object notation) வடிவில் அதன் standard input (stdin)-க்கு அனுப்பும். உங்கள் command அந்தத் தரவைப் படித்து, தனது வேலையைச் செய்து, ஒரு exit status-ஐத் தரும். ஒரு PreToolUse hook-ல் இருந்து வரும் exit 2, ஒரு tool call இயங்குவதற்கு முன்பே அதை ரத்து செய்யும். உங்கள் script standard error (stderr)-க்கு அனுப்பிய செய்தி, அதற்கான காரணமாக model-க்குத் தெரிவிக்கப்படும். ஒருவேளை அந்த hook blocking decision-ஐக் கொண்ட JSON-ஐ வெளியிட்டால், அந்த முடிவுக்கே முன்னுரிமை அளிக்கப்படும்.
இங்குள்ள event names மற்றும் field names அனைத்தும் நவம்பர் 12, 2026 அன்று சரிபார்க்கப்பட்ட Claude Code hooks reference-லிருந்து எடுக்கப்பட்டவை. இந்தத் தொழில்நுட்பம் வேகமாக மாறிவருவதால், எந்தவொரு blog post-லிருந்து JSON-ஐ நகலெடுக்கும் முன்பும் உங்கள் பதிப்பிற்கான reference-ஐச் சரிபார்க்கவும். உங்களுடையதை claude --version மூலம் அச்சிட்டுப் பார்க்கவும்.
Hook configuration எங்கு சேமிக்கப்படுகிறது
Hook என்பது settings file-ல் உள்ள ஒரு JSON block ஆகும். இதை ஆறு இடங்களில் சேமிக்கலாம்; அந்த file-ன் scope-தான் அந்த hook-ன் scope-ம் ஆகும்.
~/.claude/settings.json: உங்கள் கணினியில் உள்ள அனைத்து project-களுக்கும் பொருந்தும், மற்றவர்களுக்குப் பொருந்தாது..claude/settings.json: ஒரு குறிப்பிட்ட project-க்கு மட்டும், இது repository-ல் commit செய்யப்படுவதால், அதை clone செய்யும் அனைவருக்கும் இந்த hook கிடைக்கும்..claude/settings.local.json: ஒரு குறிப்பிட்ட project-க்கு மட்டும், உங்கள் கணினியில் மட்டும் செயல்படும்.- Managed policy settings: நிறுவனம் முழுவதும் பொருந்தக்கூடியது, இதை administrator அமைப்பார்.
hooks/hooks.json: ஒரு plugin-க்குள் இருப்பது, அந்த plugin enabled நிலையில் இருக்கும்போது மட்டும் செயல்படும்.- Skill அல்லது subagent frontmatter: ஒரு skill-ஐ அழைத்தவுடன், அந்த session முடியும் வரை அதன் hooks செயல்படும்; ஒரு subagent இயங்கும்போது அதன் hooks செயல்படும்.
இந்த file-களில் உள்ள hook entries ஒன்றையொன்று override செய்வதற்குப் பதிலாக ஒன்றிணைகின்றன (merge). ஒரு project settings file, உங்கள் user settings-ல் உள்ள hooks-ஐ நீக்காமல், அவற்றுடன் புதிய hooks-ஐச் சேர்க்கிறது. எனவே, ஒரு நிகழ்விற்கு (event) பல file-களிலிருந்து பல hooks இருக்கலாம். "disableAllHooks": true அமைப்பைச் செயல்படுத்தினால் இவை அனைத்தும் முடக்கப்படும்; ஆனால் ஒரு விதிவிலக்கு உண்டு: managed policy settings-ல் உள்ள hooks தொடர்ந்து இயங்கும், அந்த அமைப்பை managed settings-லேயே முடக்கினால் ஒழிய அவை இயங்கிக்கொண்டே இருக்கும்.
தற்போது பதிவு செய்யப்பட்டுள்ள அனைத்து hooks-களையும் பட்டியலிட, ஒரு session-க்குள் /hooks கட்டளையை இயக்கவும். இது நிகழ்வுகளின் அடிப்படையில் வகைப்படுத்தப்பட்டு, ஒவ்வொரு hook-ன் source file மற்றும் matcher-ஐக் காட்டும். இந்த menu-வை மாற்ற முடியாது (read only), எனவே settings file-ஐத் திருத்துவதன் மூலமே hook-ஐ மாற்ற முடியும். பொதுவாக, file watcher இந்த மாற்றத்தை உடனே கண்டறிந்துவிடும், நீங்கள் restart செய்ய வேண்டிய அவசியமில்லை.
Claude Code hook நிகழ்வுகள் எவை
Hooks குறிப்பு கையேடு, SessionStart முதல் SessionEnd வரை முப்பத்து மூன்று நிகழ்வுகளைப் பட்டியலிடுகிறது; இவை compaction, subagents, worktrees மற்றும் configuration files ஆகியவற்றை உள்ளடக்கியவை. Server பணிகளுக்கு இவற்றில் சில மட்டுமே பயன்படுகின்றன.
PreToolUse: ஒரு tool call இயங்குவதற்கு முன்பு,EndConversationதவிர. இதுவே தடுத்து நிறுத்தக்கூடிய (block) ஒரே நிகழ்வாகும்.PostToolUse: ஒரு tool call வெற்றிகரமாக முடிந்த பிறகு,EndConversationதவிர. அது தோல்வியுற்றால்PostToolUseFailureதூண்டப்படும்; எனவே, அனைத்து முடிவுகளையும் கண்காணிக்க வேண்டிய hook-க்கு இவை இரண்டுமே தேவை.PermissionRequest: ஒரு tool call-க்கு அனுமதி தேவைப்படும்போது, அதாவது approval prompt தோன்றும் தருணத்தில் இது நிகழும்.UserPromptSubmit: நீங்கள் ஒரு prompt-ஐ சமர்ப்பித்த பிறகு, Claude அதைச் செயலாக்குவதற்கு முன்பு. வெற்றிகரமான hook-லிருந்து வரும் plain-text stdout, model-ன் context-ல் சேர்க்கப்படும்.SessionStartமற்றும்SessionEnd: ஒரு session-ன் தொடக்கத்திலும் முடிவிலும்.SessionStart, compaction முடிந்த பிறகும்,compactஎன்ற matcher மதிப்பின்கீழ் தூண்டப்படும்.Stop: Claude தனது பதிலை முடிக்கும்போது. இது ஒரு பணி முடிந்த பிறகு அல்ல, ஒவ்வொரு turn-க்கும் ஒருமுறை நிகழும்.
Matchers-ஐ ஆதரிக்கும் நிகழ்வுகளில், ஒரு group-ஆனது matcher-ஐக் கொண்டிருக்கலாம்; இது எந்த நிகழ்வுகளுக்கு hook இயங்க வேண்டும் என்பதைத் தீர்மானிக்கிறது. Tool நிகழ்வுகளில், இது tool பெயரைக் கொண்டு வடிகட்டுகிறது; எனவே "Edit|Write" கோப்பு திருத்தங்களின்போது (file edits) மட்டுமே தூண்டப்படும். Matchers-ல் எழுத்து வடிவம் (case sensitivity) முக்கியம். காலியான matcher அனைத்து நிகழ்வுகளிலும் தூண்டப்படும். MCP (model context protocol) server-லிருந்து வரும் கருவிகள் mcp__<server>__<tool> என்று பெயரிடப்பட்டுள்ளன; எனவே "mcp__github__.*" என்ற matcher ஒரு குறிப்பிட்ட server-ன் கருவிகளை மட்டும் பிடித்து, மற்றவற்றைத் தவிர்க்கும்.
Stop hooks-ஐ எழுதும் முன் கவனிக்க வேண்டிய ஒரு சிக்கல் உள்ளது. தடுத்து நிறுத்தும் (blocking) Stop hook, model-ஐ மீண்டும் பணிக்கு அனுப்பும். இயல்பாக, தொடர்ந்து எட்டு முறை இவ்வாறு நடந்தால் Claude Code அடுத்த block-ஐ மீறிச் செயல்படும் (override); Claude ஒரு tool-ஐ அழைக்கும்போதெல்லாம் இந்த எண்ணிக்கை பூஜ்ஜியமாகும். Hook input-லிருந்து stop_hook_active புலத்தைப் படித்து, அது true எனில் exit 0 கொடுக்கவும்; இல்லையெனில், உங்கள் hook தொடர்ந்து Claude-ஐ மீண்டும் மீண்டும் பணிக்கு அனுப்பிக்கொண்டே இருக்கும்.
ஒரு hook stdin-ல் எதைப் பெறுகிறது
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"
}
}பொதுவான உள்ளீட்டு புலங்களில் session_id, cwd, transcript_path மற்றும் hook_event_name ஆகியவை அடங்கும்; permission_mode ஒவ்வொரு நிகழ்விலும் அனுப்பப்படுவதில்லை. கருவி நிகழ்வுகள் (tool events) tool_name, tool_input மற்றும் tool_use_id ஆகியவற்றைச் சேர்க்கின்றன. பிற நிகழ்வுகள் அவற்றிற்கே உரிய புலங்களைக் கொண்டுள்ளன: UserPromptSubmit ஆனது prompt உரையைப் பெறுகிறது, மேலும் SessionStart ஆனது startup, resume, clear, compact அல்லது fork ஆகியவற்றின் source-ஐப் பெறுகிறது.
ஒரு shell script-க்குள் இதைப் படிப்பதற்கு jq வழக்கமான வழியாகும், மேலும் ஒரு குறைந்தபட்ச server image-ல் இது இருக்காது. Ubuntu மற்றும் Debian-ல் sudo apt install -y jq மூலம் முதலில் இதை நிறுவவும்.
செயல்பாட்டில் உள்ள tool call-ல் exit status-ன் தாக்கம்
மூன்று வகையான முடிவுகள் உள்ளன.
- Exit 0 என்பது வெற்றியை குறிக்கும். JSON decision fields-ல் உள்ள block அல்லது denial போன்ற நிபந்தனைகள் தொடர்ந்து பொருந்தும்.
PreToolUse-ல், decision இல்லாத exit 0 என்பது அனுமதியாகாது; வழக்கமான permission flow தொடர்ந்து இயங்கும்.UserPromptSubmit,UserPromptExpansion,SessionStartமற்றும்PostModelSwitchஆகியவற்றில், plain-text stdout மாதிரியின் (model) context-ல் சேர்க்கப்படும். மற்ற நிகழ்வுகளில், stdout debug log-க்கு மட்டுமே செல்லும். - Exit 2 என்பது தடுக்கக்கூடிய நிகழ்வுகளில் அந்தச் செயலைத் தடுக்கும்;
PreToolUseஅவற்றில் ஒன்று. JSON output-ல் தடுப்பதற்கான காரணம் இல்லையெனில், stderr-ல் உள்ள செய்தி தடுப்புச் செய்தியாகக் கருதப்படும். அந்தச் செய்தியை யார் பார்ப்பார்கள் என்பது நிகழ்வைப் பொறுத்தது.PreToolUseமற்றும்Stop-ல், மாதிரி (model) அதைத் தடுப்புக்கான காரணமாகக் கருதும்.UserPromptSubmitமற்றும்PreModelSwitch-ல், அது உங்களுக்குக் காட்டப்படும், ஆனால் மாதிரியின் context-ல் சேர்க்கப்படாது. தடுக்க முடியாதPostToolUseமற்றும்PostToolUseFailureநிகழ்வுகளில், தடுப்பு புறக்கணிக்கப்படும், ஆனால் stderr மாதிரிக்கான பின்னூட்டமாக (feedback) செல்லும். தடுக்க முடியாத மற்ற நிகழ்வுகளில், stderr உங்களுக்கு மட்டுமே காட்டப்படும் அல்லது புறக்கணிக்கப்படும்.Stop,SubagentStop,TaskCompletedமற்றும் ஒரு plugin-ன்UserPromptSubmithook ஆகியவற்றில், stdout காலியாக இருந்து stderr-ல் missing-file பிழை இருந்தால், அது தடுக்காத பிழையாகக் கருதப்படும். - பிற exit code-கள் மற்றும் plain-text அல்லது காலியான stdout வழக்கமாகத் தடுக்காத பிழைகளாகக் கருதப்படும். Transcript-ல்
Failed with non-blocking status code:என்ற உரைக்குப் பிறகு stderr-ன் முதல் வரியுடன் கூடிய hook error notice காட்டப்படும்.PreToolUseபோன்ற நிகழ்வுகளில், hook தோல்வியடைந்து செயலைத் தடுக்காத வரை, சரியான JSON முடிவை எடுக்க முடியும்.WorktreeCreateஎந்தவொரு nonzero exit-லும் தோல்வியடையும்;WorktreeRemove, செயல் முடிந்த பிறகும் directory இருந்தால், nonzero exit-ல் தோல்வியடையும்.
தடுப்பது அல்லது அமைதியாக இருப்பதைத் தாண்டிச் செயல்பட, exit 0-ஐப் பயன்படுத்தி JSON object-ஐ stdout-ல் அச்சிடவும். ஒரு PreToolUse hook, permissionDecision மூலம் முடிவெடுக்கும்:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database drops go through a migration, not through the agent."
}
}"allow", அனுமதி விதிகள் மற்றும் tool-ன் ஒப்புதல் தேவைகள் அனுமதிக்கும் இடங்களில் interactive prompt-ஐத் தவிர்க்கும். "deny" அழைப்பை ரத்து செய்து அதற்கான காரணத்தை மாதிரியிடம் அனுப்பும். "ask" உறுதிப்படுத்தலைக் கோரும். ஒரு hook-க்கு ஒரு பாணியைத் தேர்ந்தெடுக்கவும். Exit 2-ஐ stdout-ல் உள்ள JSON முடிவோடு இணைத்தால், JSON-ல் "allow" என்று இருந்தாலும், தடுப்பு (block) தொடரும்.
ஒரே நிகழ்விற்குப் பல hooks பொருந்தினால், அவை இணையாக (parallel) இயங்கும். Prompt மற்றும் agent hooks ஒரே நேரத்தில் பன்னிரண்டு வரை மட்டுமே இயங்க முடியும். ஒரு hook-ல் இருந்து வரும் deny அதன் மற்ற hooks-ஐ நிறுத்தாது. எனவே, ஒரு guardrail hook அழைப்பை மறுக்கும்போதும், logging hook தனது வரியைப் பதிவு செய்யும். PreToolUse-க்கு, Claude Code பதில்களை ஒருங்கிணைத்து, deny, defer, ask, allow என்ற வரிசையில் மிகவும் கடுமையான முடிவைத் தக்கவைக்கும்.
உதாரணம் 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இதை 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"
}
]
}
]
}
}நீங்கள் அதை நம்புவதற்கு முன், ஸ்கிரிப்டை கைமுறையாகச் சோதிக்கவும். ஏனெனில், அதன் உள்ளீட்டிலேயே செயலிழக்கும் ஒரு hook, onFailure அமைக்கப்படாதபோது பொதுவாகத் தடையின்றி இயங்கிவிடும் (fails open). Git Bash இல்லாத Windows-ல், செயலிழக்கும் shell-form PreToolUse அல்லது PermissionRequest கட்டளை hook, கருவியின் செயல்பாட்டைத் தடுக்கக்கூடும்:
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
| .claude/hooks/block-destructive.sh
echo $?நீங்கள் stderr-ல் Blocked by policy: வரியையும், 2 என்ற exit code-ஐயும் பார்க்க வேண்டும். ls -la போன்ற பாதிப்பில்லாத கட்டளையை உள்ளீடாகக் கொடுத்தால், எந்த வெளியீடும் இருக்கக்கூடாது மற்றும் exit code 0 என இருக்க வேண்டும். ஒரு session-ல், மறுக்கப்பட்ட கட்டளை உங்கள் காரணத்துடன் transcript-ல் தோன்றும்; அதை model படித்து அதற்கேற்ப தன்னை மாற்றிக்கொள்ளும்.
இந்தச் செயல் பயனுள்ளதாக இருப்பதற்கு ஒரு முக்கிய காரணம் உள்ளது: PreToolUse hooks, permission-mode சரிபார்ப்பிற்கு முன்பே இயங்குகின்றன. இது அனைத்து permission mode-களிலும் நடப்பதால், bypassPermissions-ன் கீழும் இந்தத் தடை நீடிக்கும். இதுவே Claude Code auto mode மற்றும் அதன் அனுமதி அமைப்புகள் போன்றவற்றுடன் இந்த hook-ஐப் பயனுள்ளதாக்குகிறது; அங்கு prompts குறைக்கப்பட்டாலும், இந்த hook தொடர்ந்து இயங்கும்.
இது என்ன என்பதை வெளிப்படையாகப் புரிந்துகொள்ளுங்கள். ஒரு கட்டளைச் சரத்தை (command string) pattern matching செய்வது, ஒரு agent கவனக்குறைவாகச் செயல்படுவதைத் தடுக்கும் ஒரு பாதுகாப்பு அரணே தவிர, அது புத்திசாலித்தனமாகச் செயல்படுவதைத் தடுக்கும் எல்லை அல்ல. ஏனெனில், அதே கட்டளையை உங்கள் grep பார்க்க முடியாத வடிவத்தில் எழுத முடியும். கடுமையான விதிகள் (hard rules) என்பவை permission system-லும், அந்தச் செயல்முறை இயங்கும் account-லும் மட்டுமே இருக்க வேண்டும்.
உதாரணம் 2: ஒவ்வொரு திருத்தத்திற்குப் பிறகும் format மற்றும் lint செய்தல்
PostToolUse மற்றும் Edit|Write matcher ஆகியவற்றை உள்ளடக்கிய அமைப்பு, இந்த இரண்டு கோப்புத் திருத்தக் கருவிகளில் ஏதேனும் ஒன்று வெற்றிகரமாக முடிந்ததும் இயங்கும். இதை .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
}
]
}
]
}
}ஒரு Python கோப்பில் தவறான indentation கொண்ட function-ஐச் சேர்க்க Claude-இடம் கேட்கவும், பிறகு அந்தக் கோப்பைத் திறக்கவும். அது தானாகவே format செய்யப்பட்டு வரும். hook வெற்றிகரமாக இயங்கியதை இது உறுதிப்படுத்துகிறது, ஏனெனில் ஒரு வெற்றிகரமான hook செயல்பாட்டின் போது உரையாடலில் எந்தத் தகவலும் காட்டப்படாது.
இங்குள்ள exit 2 எதையும் மாற்றாது. PostToolUse என்பது கருவி ஏற்கனவே இயங்கிய பிறகு செயல்படுவதால், அந்தத் திருத்தம் எப்படியும் வட்டில் (disk) சேமிக்கப்பட்டுவிடும். exit 2-ஐப் பயன்படுத்துவதன் நோக்கம், ruff check வெளியீட்டை ஒரு பின்னூட்டமாக (feedback) மாதிரிக்கு (model) கொண்டு செல்வதே ஆகும்; இதன் மூலம், அது அடுத்த கட்டத்திற்குச் செல்லாமல், தான் செய்த பிழையைத் தானே சரிசெய்து கொள்ளும். commit செய்யும் நேரத்தில் கண்டறியப்படும் lint பிழைக்கும், இந்தச் சுழற்சியிலேயே முகவர் (agent) சரிசெய்யும் பிழைக்கும் உள்ள வித்தியாசம் இதுதான்.
இங்கு இரண்டு matcher வரம்புகள் முக்கியமானவை. Edit|Write என்பது shell command மூலம் மாற்றப்படும் கோப்புகளைக் கவனிக்காது, மேலும் Claude அடிக்கடி Bash வழியாகக் கோப்புகளை எழுதுவதால் இந்த இடைவெளி உண்மையானது. ஒவ்வொரு அழைப்பிற்கும் (per-call) பாதுகாப்பு கிடைக்க, Bash-ஐ matcher-ஆகச் சேர்த்து, git status --porcelain மூலம் மாற்றப்பட்ட கோப்புகளின் பட்டியலை script-ல் பெறவும். ஒரு turn-க்கு ஒருமுறை (once-per-turn) பாதுகாப்பு கிடைக்க, அந்தச் சோதனையை Stop hook-ல் வைக்கவும்.
உதாரணம் 3: தணிக்கைக்காக ஒவ்வொரு tool call-ஐயும் log செய்தல்
PostToolUse-ல் உள்ள ஒரு காலி matcher, EndConversation-ஐத் தவிர மற்ற அனைத்து வெற்றிகரமான tool call-களிலும் இயங்கும். பதிவுகளை home directory-ல் உள்ள ஒரு கோப்பிற்கு அனுப்புவதற்குப் பதிலாக system journal-க்கு அனுப்புவது, அவற்றை agent-ன் shell-லிருந்து மறைக்காது: அணுகல் என்பது அந்த account-ன் அனுமதிகளைப் பொறுத்தது. பயனர்கள் தங்கள் சொந்த private 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-ஐத் தவிர மற்ற வெற்றிகரமான tool call-களுக்கான JSON வரியை ஒவ்வொன்றாகக் காணலாம் (புதியவை கடைசியில் இருக்கும்). எதுவும் தெரியவில்லை என்றால், journal அணுகலையும், hook இயங்கியதா என்பதையும் சரிபார்க்கவும்; கீழே உள்ள troubleshooting பகுதியில் hook பற்றிய விவரங்கள் உள்ளன.
தோல்வியுற்ற அழைப்புகளைப் பிடிக்க PostToolUseFailure-ன் கீழ் அதே தொகுப்பைச் சேர்க்கவும், ஏனெனில் PostToolUse வெற்றியின் போது மட்டுமே இயங்கும், மேலும் தோல்வியுற்ற கட்டளைகளே பெரும்பாலும் முக்கியமானவை. உங்கள் home directory-ல் உள்ள கோப்பில் சேர்ப்பதற்குப் பதிலாக logger-ஐப் பயன்படுத்துவதற்கான காரணம் உரிமை (ownership) ஆகும்: ஒரு hook, agent-ன் shell இயங்கும் அதே பயனராகவே இயங்குகிறது, எனவே அந்தப் பயனர் எதில் எழுத முடியுமோ, அதை அவரால் அழிக்கவும் (truncate) முடியும். journal-ஐ systemd-journald எழுதுகிறது; அதை நீக்காமல் பாதுகாப்பது இன்னும் agent account-ன் சலுகைகளையே பொறுத்தது.
ஒரு 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 வினாடிகள் வரை இயங்கும், இது பத்து நிமிடங்களுக்குச் சமம். சில நிகழ்வுகள் இந்த நேரத்தை வெகுவாகக் குறைக்கின்றன. SessionEnd hooks அனைத்தும் சேர்ந்து மொத்தம் 1.5 வினாடிகள் என்ற கால அளவை மட்டுமே பகிர்ந்து கொள்கின்றன, எனவே அமர்வின் இறுதியில் செய்யப்படும் cleanup பணிகள் விரைவாக இருக்க வேண்டும். இருப்பினும், உங்கள் settings கோப்புகளில் ஒரு hook-க்கு நீண்ட timeout மதிப்பை அமைப்பதன் மூலம், அந்தப் பகிரப்பட்ட கால அளவை 60 வினாடிகள் வரை அதிகரிக்க முடியும்.
ஒரு synchronous command, HTTP அல்லது MCP tool hook அதன் கால அளவை (timeout) எட்டினால், அது ரத்து செய்யப்படும் மற்றும் பொதுவாக எந்த முடிவையும் வழங்காது; PreModelSwitch-ல், ஒரு timeout நிகழ்வு அந்த switch-ஐத் தடுக்கும். ஒரு PreToolUse guardrail-ஐப் பொறுத்தவரை, timeout நிகழ்ந்தால் பொதுவாக அந்த tool call வழக்கமான அனுமதி ஓட்டத்திற்கு (permission flow) அனுமதிக்கப்படும். onFailure அமைக்கப்படாத நிலையில், மேலே குறிப்பிட்ட Windows விதிவிலக்கு இதற்குப் பொருந்தும். இந்த காரணத்திற்காக guardrail scripts-ஐச் சிறியதாக வைத்திருக்கவும். 2.1.295 release-க்கு பிறகு, command அல்லது http hook-களில் "onFailure": "block"-ஐப் பயன்படுத்தி இந்த இயல்புநிலையை மாற்றலாம். இது ஒரு timeout, crash அல்லது எதிர்பாராத exit code-ஐத் தடுப்பாக (block) மாற்றும். இருப்பினும், இது Stop, SubagentStop, TaskCompleted, TeammateIdle அல்லது background command hooks-ல் எந்த மாற்றத்தையும் ஏற்படுத்தாது. log-ஐ வேறொரு இடத்திற்கு அனுப்புவது போன்ற, எவரும் காத்திருக்கத் தேவையில்லாத மெதுவான பணிகளுக்கு, "async": true-ஐ அமைக்கவும்; அப்போது அந்த hook, tool call-ஐத் தாமதப்படுத்தாமல் பின்னணியில் (background) இயங்கும்.
Hooks, rules files, skills மற்றும் MCP servers
ஒரு agent-ன் செயல்பாட்டை மாற்றும் நான்கு விஷயங்கள் குழப்பத்தை ஏற்படுத்தலாம். அவற்றில் ஒன்று மட்டுமே பரிந்துரை என்பதைத் தாண்டி கட்டாயமாகச் செயல்படுகிறது.
ஒரு rules file (CLAUDE.md, அல்லது .claude/rules/-ன் கீழ் உள்ள ஒரு கோப்பு) என்பது model-ன் context-ல் ஏற்றப்படும் உரை ஆகும். இது நடத்தையை வடிவமைக்குமே தவிர, எதையும் கட்டாயப்படுத்தாது. நீண்ட உரையாடல், பெரிய diff மற்றும் புதிய பயனர் கோரிக்கை ஆகியவற்றிற்கு மத்தியில், இதில் உள்ள ஒரு வரி கவனிக்கப்படாமல் போகலாம். நீங்கள் எழுதிய அறிவுறுத்தல்களை agents புறக்கணிப்பதற்கான சாதாரண காரணம் இதுதான்.
ஒரு skill என்பது, அது பொருத்தமானது என்று model கருதும் போது ஏற்றப்படும் அறிவுறுத்தல்கள் மற்றும் scripts அடங்கிய கோப்புறை ஆகும். அந்தத் தீர்மானமே ஒரு skill-ன் அடிப்படை, அதே சமயம் அதுவே அதன் எல்லையும் கூட: இறுதி முடிவு model-ஆலேயே எடுக்கப்படுகிறது. Ponytail, இது ஒரு agent-ஐ மிகச்சிறிய மாற்றத்தை நோக்கித் தள்ளுகிறது போன்ற ஒரு skill-ல் இந்த இரண்டு பக்கங்களையும் நீங்கள் காணலாம். இது ஒரு பணியை அணுகும் முறையை எந்த ஒரு hook-ஆலும் செய்ய முடியாத வகையில் வடிவமைக்கிறது, ஆனால் model அதை ஏற்றத் தேர்ந்தெடுக்கும் வரை மட்டுமே இது செயல்படும்.
ஒரு MCP (model context protocol) server, model-க்கு அழைப்பதற்கான புதிய கருவிகளை வழங்குகிறது. இது agent-ன் செயல்பாட்டு எல்லையை விரிவுபடுத்துகிறது. இது agent-ஐ எதையும் செய்யத் தூண்டுவதில்லை, மேலும் இதை நீங்கள் தனிப்பட்ட process-ஆக இயக்க வேண்டும், இது ஒரு தனிப் பணியாகும்: VPS-ல் MCP servers-ஐ இயக்குவது என்பதைப் பார்க்கவும்.
இந்த நான்கில், model-ன் தேர்வு இன்றி இயங்கும் ஒரே விஷயம் hook மட்டுமே. ஒரு விருப்பத்திற்கு rules file-ஐயும், ஒரு செயல்முறைக்கு skill-ஐயும் பயன்படுத்தவும். ஒவ்வொரு முறையும் நடக்க வேண்டிய அல்லது ஒருபோதும் நடக்கக்கூடாத ஒரு செயலுக்கு hook-ஐப் பயன்படுத்தவும். ஒரு skill எப்போது rules file-ஐ விடச் சிறந்தது என்பது உட்பட விரிவான ஒப்பீட்டிற்கு, skills, MCP மற்றும் rules files ஒப்பீடு என்பதைப் பார்க்கவும்.
Plugin என்பது ஐந்தாவது வழிமுறை அல்ல, அது ஒரு தொகுப்பு முறை மட்டுமே. இது hooks மற்றும் skills-ஐ ஒரே install செய்யக்கூடிய அலகாக மாற்றுகிறது. இதன் மூலம் ஒரு குழு ஒரே guardrail-ஐ அனைத்து கணினிகளிலும் பயன்படுத்த முடியும்: Claude Code plugins எவ்வாறு செயல்படுகின்றன என்பதைப் பார்க்கவும்.
பகிரப்பட்ட VPS-ல் பாதுகாப்பு முடிவுகள்
Hook என்பது agent-ஆல் தூண்டப்படும் code; இது Claude Code-ஐத் தொடங்கிய பயனரின் உரிமைகளிலேயே இயங்கும். இது அந்தப் பயனரின் file permissions மற்றும் environment-ஐ அப்படியே பெறும். ஒரு laptop-ல் இது workflow சார்ந்த கேள்வி. ஆனால், ஒரு agent கவனிக்கப்படாமல் இயங்கும் VPS-ல், இது நான்கு நடைமுறைப் பகுதிகளைக் கொண்ட ஒரு பாதுகாப்புச் சிக்கலாகும்.
Repository-ல் உள்ள hook நீங்கள் எழுதாத code. .claude/settings.json என்பது commit செய்யப்பட்ட ஒன்று. எனவே, ஒரு repository-ஐ clone செய்து அதற்குள் session-ஐத் தொடங்கும்போது, அந்த repository-யுடன் வந்த hooks-ம் பதிவாகலாம். ஒரு interactive session-ல், அந்த folder-க்கான workspace trust dialog மூலம் Claude Code project hooks-ஐக் கட்டுப்படுத்தும். அதாவது, நீங்கள் trust-ஐ ஏற்றுக்கொள்வதுதான் அவற்றை இயக்குவதற்கான தருணம். முதலில் hooks block-ஐப் படிக்கவும். ஒரு claude -p அல்லது SDK session-ல், கவனிக்கப்படாமல் இயங்கும் agent-க்கு அந்த dialog காட்டப்படாது; அது அந்த folder-ஐ trusted-ஆகக் கருதும். எனவே, repository-ன் hooks கேட்காமலேயே இயங்கும். அதைப் பயன்படுத்தும் முன் அதன் .claude/ files-ஐ ஆய்வு செய்யவும் அல்லது --settings '{"disableAllHooks": true}' மூலம் இயக்கவும்.
Hook முழுமையான tool input-ஐப் பார்க்கும். tool_input-ஐ log செய்யும் ஒரு audit hook, ஒவ்வொரு command-ன் அனைத்து arguments-களையும் log-ல் எழுதும். இதில் command line-ல் இருந்த ஏதேனும் token-ம் அடங்கும். அந்த log-க்கு, ரகசியத் தரவுகளுக்குத் தேவைப்படும் அதே பாதுகாப்பு அவசியம். இது AI agent-ன் அணுகலுக்கு அப்பாற்பட்டு ரகசியங்களைப் பாதுகாத்தல் என்ற பரந்த சிக்கலின் ஒரு பகுதியாகும்.
Hook model-ன் context-ல் எழுத முடியும். வெற்றிகரமான SessionStart அல்லது UserPromptSubmit hook-ன் plain-text stdout உரையாடலில் சேர்க்கப்படும். வெளியிலிருந்து, அதாவது issue tracker அல்லது log file-லிருந்து text-ஐ pipe செய்யும் ஒரு hook, நீங்கள் நீங்களே தட்டச்சு செய்தது போல நம்பகத்தன்மையற்ற text-ஐ model-க்கு வழங்குகிறது. அதே VPS-ல் உள்ள மற்றொரு Claude Code session-லிருந்து ஒரு குறிப்பை அனுப்பும் hook-ம் இதையே செய்கிறது. ஒரு agent-ன் வெளியீடு, issue tracker-ஐ விட அதிக நம்பிக்கைக்குரியது அல்ல. அந்த stdout-ஐ வெளியீடாகக் கருதாமல் உள்ளீடாகக் கருதி கையாளவும்.
அதிகாரமே (Privilege) உண்மையான கட்டுப்பாடு. Agent-ஐ ஒரு பிரத்யேக, குறைந்த அதிகாரம் கொண்ட (unprivileged) பயனராக இயக்கி, அதற்குத் தேவையான sudo விதிகளை மட்டும் வழங்கவும். ஒரு PreToolUse deny இருப்பது நல்லது, ஆனால் அது வடிவமைப்பிலேயே சிறந்த முயற்சியாகவே (best effort) இருக்கும். if filter-ஐப் பற்றியும் reference இதையே கூறுகிறது. உங்களுக்குக் கடுமையான தடை (hard deny) தேவைப்படும்போது permission system-ஐப் பயன்படுத்த அறிவுறுத்துகிறது. Permission விதிகள் மற்றும் process இயங்கும் கணக்கு ஆகியவையே அழுத்தமான சூழலிலும் நிலைத்து நிற்கும்.
ஒவ்வொரு permission mode-லும் ஒரு பண்பு மாறாமல் இருக்கும். PreToolUse hooks அனைத்து permission mode-களிலும் permission-mode சரிபார்ப்புக்கு முன்பே இயங்கும். எனவே, bypassPermissions-ல் கூட ஒரு hook deny-ஐத் திருப்பியளித்தால் அது tool-ஐத் தடுக்கும். Hooks, permission விதிகள் அனுமதிப்பதை இன்னும் இறுக்கமாக்க முடியுமே தவிர, தளர்த்த முடியாது. இதற்கு mod ஒரு விதிவிலக்கு. நிர்வகிக்கப்படும் settings மற்றும் managed-mcp.json file இல்லாத ஒரு கணினியில், Team அல்லது Enterprise plan-க்கு /login மூலம் உள்நுழையாத ஒரு session-ல், tool.check-ஐக் கையாளும் ஒரு mod, உங்கள் PreToolUse hook தடுத்த ஒரு call-ஐ அனுமதிக்கலாம். நிர்வகிக்கப்படும் settings, managed-mcp.json file அல்லது Team/Enterprise /login சான்றுகளைக் கொண்ட session-ல், PreToolUse hook தடுத்த ஒரு call, எந்த settings file-லிருந்து வந்தாலும் இயல்பாகவே தடுக்கப்பட்டிருக்கும். API key அல்லது நீண்ட காலம் இயங்கும் CLAUDE_CODE_OAUTH_TOKEN மூலம் இயங்கும் session, பல servers-ல் பயன்படுத்தப்படுவது போல, login சேமிக்கப்பட்டிருந்தாலும் உள்நுழையாததாகவே கருதப்படும். ஒரு server-ல் நிறுவும் முன் Claude Code mods எதை மாற்ற முடியும் என்பதைச் சரிபார்க்கவும்.
எனது hook ஏன் செயல்படவில்லை?
இதை வரிசையாகச் சரிபார்க்கவும். ஒவ்வொரு படியும் நீங்கள் காணும் அறிகுறியைக் குறிப்பிடுகிறது.
/hooksகட்டளையை இயக்கி, நீங்கள் எதிர்பார்த்த event-ன் கீழ் hook உள்ளதா என்று பார்க்கவும். மெனுவில் hook இல்லை என்றால், settings கோப்பில் JSON syntax பிழை இருக்கலாம்; ஏனெனில் trailing commas மற்றும் comments அனுமதிக்கப்படாது, அல்லது கோப்பு மேலே உள்ள ஆறு இடங்களில் ஒன்றில் இல்லை என்று அர்த்தம்.- Matcher-ஐ tool பெயருடன் துல்லியமாக ஒப்பிடவும். Matcher-கள் case sensitive என்பதால்,
"bash"என்பது ஒருபோதும்Bashtool-உடன் பொருந்தாது. - மேலே உள்ள உதாரணம் 1-ல் உள்ளது போல, sample input-ஐக் கொண்டு script-ஐ நீங்களே நேரடியாக இயக்கவும். நீங்கள் எதிர்பாராத exit code உங்கள் script-ல் உள்ள பிழையைக் குறிக்கிறது; அதன் stdout-ஐயும் சரிபார்க்கவும், ஏனெனில் சரியான JSON கூட
PreToolUseபோன்ற நிகழ்வுகளுக்கு முடிவுகளை வழங்கக்கூடும். jq: command not foundஎன்ற அறிவிப்பு வந்தால், அந்த machine-ல்jqஇல்லை என்று அர்த்தம். உங்கள் சொந்த script-க்குcommand not foundஎன்று வந்தால், path சரியாகக் கண்டறியப்படவில்லை என்று பொருள்; எனவே${CLAUDE_PROJECT_DIR}அல்லது absolute path-ஐப் பயன்படுத்தவும். script இயங்கவே இல்லை என்றால், அது executable நிலையில் இல்லாமல் இருக்கலாம்.- Hook சரியான JSON-ஐ அச்சிடுகிறது, ஆனால் எதுவும் நடக்கவில்லை. macOS மற்றும் Linux-ல், shell-form hook ஒரு non-interactive shell-ல்
sh -cவழியாக இயங்குகிறது. இருப்பினும், சில அமைப்புகளில்BASH_ENVஎன்பது~/.bashrc-ஐக் குறிப்பது போல உங்கள் profile-ஐ source செய்யலாம். அந்த profile ஏதேனும் banner-ஐ அச்சிட்டால், அது உங்கள் JSON-க்கு முன்னால் சேர்க்கப்படும். Stdout இப்போது{-ல் தொடங்காது, எனவே Claude Code முழுவதையும் plain text-ஆகக் கருதி முடிவை நிராகரிக்கும். Hook 0 exit code-ஐக் கொடுத்ததால், transcript-ல் எந்தப் பிழையும் காட்டாது. பெரும்பாலான நிகழ்வுகளில் அந்த உரை debug log-க்கு மட்டுமே செல்லும், ஆனால்UserPromptSubmit,UserPromptExpansion,SessionStartமற்றும்PostModelSwitchநிகழ்வுகளில், banner உட்பட அனைத்தும் model-ன் context-ல் சேர்க்கப்படும். உங்கள் profile-ல் உள்ள ஏதேனும்echo-ஐ interactive shell-ல் மட்டும் இயங்குமாறு மாற்றவும். - இன்னும் சிக்கல் நீடித்தால்:
claude --debug-file /tmp/claude.logகொண்டு session-ஐத் தொடங்கி, இரண்டாவது terminal-ல்tail -f /tmp/claude.log-ஐ இயக்கவும். எந்தெந்த hooks பொருந்தின, ஒவ்வொன்றும் என்ன exit code-ஐத் திரும்ப அளித்தன, மற்றும் அவை stdout/stderr-ல் என்ன எழுதின என்பதை debug log பதிவு செய்யும்.
FAQ
Claude Code hook மற்றும் CLAUDE.md instruction ஆகியவற்றுக்கு இடையே உள்ள வேறுபாடு என்ன?
ஒரு CLAUDE.md instruction என்பது model-ன் context-ல் உள்ள உரையாகும். எனவே, இது உரையாடல் மற்றும் தற்போதைய கோரிக்கையுடன் கவனத்தைப் பெறுவதற்குப் போட்டியிடும்; model இதை மற்றவற்றுடன் ஒப்பிட்டு எடைபோட முடியும். ஒரு hook என்பது Claude Code அதன் lifecycle-ல் ஒரு குறிப்பிட்ட புள்ளியில் இயக்கும் shell command ஆகும். எனவே, model என்ன முடிவெடுத்தாலும், அந்த நிகழ்வு நடக்கும்போதெல்லாம் இது இயங்கும். ஒரு விருப்பத்தை (preference) தெரிவிக்க instruction-ஐப் பயன்படுத்தவும். எப்போதும் நடக்க வேண்டிய ஒரு படி அல்லது ஒருபோதும் நடக்கக்கூடாத ஒரு செயலுக்கு hook-ஐப் பயன்படுத்தவும்.
ஒரு குறிப்பிட்ட shell command-ஐ Claude Code இயக்குவதைத் தடுப்பது எப்படி?
ஒரு PreToolUse hook-ஐ, Bash matcher-உடன் பதிவு செய்யவும். இது .tool_input.command-லிருந்து command-ஐப் படித்து, stderr-ல் ஒரு காரணத்தை எழுதி, 2 என்ற exit code-ஐ வழங்கும். Claude Code அந்த அழைப்பை ரத்து செய்து, உங்கள் காரணத்தை model-க்குக் காட்டும். இது permission-mode சரிபார்ப்புக்கு முன்பே நடப்பதால், bypassPermissions mode-ல் கூட இந்தத் தடை செல்லும். ஒரு command string-ஐ pattern matching செய்வது ஒரு பாதுகாப்பு அரண் (guardrail) மட்டுமே, இது ஒரு முழுமையான பாதுகாப்பு எல்லை (security boundary) அல்ல. ஏனெனில், அதே command-ஐ pattern கவனிக்காத வகையில் எழுத முடியும். எனவே, இதை permission rules மற்றும் unprivileged account மூலம் உறுதிப்படுத்தவும்.
எனது hook சரியான JSON-ஐ வெளியிடுகிறது, ஆனால் எதுவும் நடக்கவில்லை. ஏன்?
JSON-க்கு முன்னால் ஏதேனும் உரை அச்சிடப்படுகிறதா என்று உங்கள் shell profile-ஐச் சரிபார்க்கவும். macOS மற்றும் Linux-ல், args field இல்லாத ஒரு hook, sh -c வழியாக இயங்கும். BASH_ENV என்பது ~/.bashrc-ஐக் குறிக்கும் அமைப்புகளில், உங்கள் profile-ஐ source செய்யும் போது, banner-ஐ அச்சிடும் profile அந்த உரையை உங்கள் JSON-க்கு முன்னால் stdout-ல் வைக்கும். வெளியீடு {-ல் தொடங்காததால், Claude Code அதை வெறும் உரையாகக் கருதி முடிவைப் புறக்கணிக்கும். hook 0 என்ற exit code-ஐக் கொடுத்ததால், transcript-ல் எந்தப் பிழையும் காட்டப்படாது. உங்கள் profile-ல் உள்ள ஏதேனும் echo-ஐ interactive-shell test மூலம் பாதுகாக்கவும், பின்னர் claude --debug-file /tmp/claude.log-லிருந்து debug log-ஐப் படித்துத் தீர்வை உறுதிப்படுத்தவும்.
பகிரப்பட்ட server-ல் Claude Code hooks-ஐ இயக்குவது பாதுகாப்பானதா?
Hooks, Claude Code-ஐத் தொடங்கிய பயனரின் உரிமைகளுடன் (permissions) இயங்கும். எனவே, அந்த account-ஆல் என்ன செய்ய முடியுமோ, அதை hook-ஆலும் செய்ய முடியும். இரண்டு பழக்கங்கள் பெரும்பாலான அபாயங்களைக் குறைக்கும்: agent-ஐக் குறைந்த உரிமைகள் கொண்ட (unprivileged) account-ல், குறுகிய sudo policy-உடன் இயக்கவும். எந்தவொரு repository-ன் workspace trust dialog-ஐ ஏற்றுக்கொள்வதற்கு அல்லது அதில் claude -p-ஐ இயக்குவதற்கு முன்பு, அதன் hooks block-ஐப் படிக்கவும். ஏனெனில் project hooks, .claude/settings.json-க்குள் வருகின்றன, மேலும் -p mode அந்த dialog-ஐ ஒருபோதும் காட்டாது. hooks-ஐ முடக்க உங்கள் settings file-ல் "disableAllHooks": true-ஐ அமைக்கவும்; managed level-ல் தேவைப்படும் managed hooks-க்கு இது பொருந்தாது. false என்ற project setting, true என்ற user setting-ஐ மீறிச் செயல்படக்கூடும்.