SSD Nodes Learn Hosting plans →
गाइड Matt Connorलेखक: Matt Connor

Claude Code hooks कैसे काम करते हैं और इनका उपयोग

Claude Code hooks के कार्य करने के तरीके को समझें। जानें कि ये कमांड्स मॉडल की सहमति के बिना कैसे चलते हैं, exit code 2 का प्रभाव क्या है और सुरक्षा के लिए इनका महत्व क्या है।

Claude Code hook क्या है

Claude Code hooks वे shell commands हैं जिन्हें Claude Code अपने lifecycle के निश्चित बिंदुओं पर स्वयं चलाता है। hook और rules file के बीच यही मुख्य अंतर है। CLAUDE.md में दिया गया निर्देश एक सलाह है, और model इसे अपने context में मौजूद अन्य सभी चीजों के साथ तौलकर देखता है। hook एक code है, और यह model की सहमति हो या न हो, चलता ही है। यदि आपका agent बार-बार उस formatter को छोड़ देता है जिसके बारे में आपने उसे दो बार बताया है, तो आपको अधिक सख्त निर्देश की नहीं, बल्कि एक hook की आवश्यकता है।

यह mechanism बहुत छोटा है। आप settings file में एक event name के अंतर्गत एक command register करते हैं। जब वह event trigger होता है, तो Claude Code आपकी command चलाता है और event data को JSON (JavaScript object notation) के रूप में standard input (stdin) पर लिखता है। आपकी command उस data को पढ़ती है, अपना काम करती है, और exit status के साथ उत्तर देती है। PreToolUse hook से exit 2 आने पर tool call चलने से पहले ही रद्द हो जाती है, और आपकी script ने standard error (stderr) पर जो भी लिखा होता है, वह कारण के रूप में model को वापस भेज दिया जाता है, जब तक कि hook कोई blocking decision वाला JSON न प्रिंट करे, जिसका कारण प्राथमिकता लेता है।

यहाँ दिए गए event names और field names Claude Code hooks reference से लिए गए हैं, जिन्हें 12 नवंबर, 2026 को जाँचा गया था। यह क्षेत्र तेजी से बदल रहा है, इसलिए किसी भी blog post (इसे भी शामिल करते हुए) से JSON कॉपी करने से पहले अपने version के लिए reference जरूर देखें। अपना JSON claude --version के साथ प्रिंट करें।

हुक कॉन्फ़िगरेशन कहाँ स्थित होता है

हुक एक सेटिंग्स फ़ाइल में मौजूद JSON ब्लॉक होता है। इसे छह स्थानों पर रखा जा सकता है, और फ़ाइल का स्कोप ही हुक का स्कोप होता है।

  • ~/.claude/settings.json: आपकी मशीन पर मौजूद हर प्रोजेक्ट के लिए, और किसी अन्य के लिए नहीं।
  • .claude/settings.json: एक प्रोजेक्ट के लिए, जिसे रिपॉजिटरी में कमिट किया जाता है, ताकि इसे क्लोन करने वाले हर व्यक्ति को वह हुक मिल जाए।
  • .claude/settings.local.json: एक प्रोजेक्ट के लिए, केवल आपकी मशीन पर।
  • मैनेज्ड पॉलिसी सेटिंग्स: पूरे संगठन के लिए, जिसे एक एडमिनिस्ट्रेटर द्वारा सेट किया जाता है।
  • hooks/hooks.json एक प्लगइन के अंदर, जो तब तक सक्रिय रहता है जब तक वह प्लगइन इनेबल रहता है।
  • स्किल या सब-एजेंट फ्रंटमैटर। एक बार स्किल इनवोक होने के बाद, स्किल के हुक सेशन के बाकी समय तक सक्रिय रहते हैं, और सब-एजेंट के हुक तब तक सक्रिय रहते हैं जब तक वह सब-एजेंट चलता है।

इन फ़ाइलों से हुक एंट्रीज़ एक-दूसरे को ओवरराइड करने के बजाय मर्ज हो जाती हैं। एक प्रोजेक्ट सेटिंग्स फ़ाइल अपने हुक को आपकी यूज़र सेटिंग्स में मौजूद हुक के साथ जोड़ती है, न कि उन्हें बदलती है, इसलिए एक इवेंट में कई फ़ाइलों से कई हुक हो सकते हैं। "disableAllHooks": true सेटिंग उन्हें बंद कर देती है, लेकिन एक अपवाद है: मैनेज्ड पॉलिसी सेटिंग्स से आने वाले हुक तब तक चलते रहते हैं जब तक कि वह सेटिंग मैनेज्ड सेटिंग्स में भी लागू न की जाए।

वर्तमान में रजिस्टर्ड हर हुक को लिस्ट करने के लिए सेशन के अंदर /hooks चलाएं, जो इवेंट के अनुसार समूहीकृत होंगे और प्रत्येक के लिए सोर्स फ़ाइल और मैचर दिखाएंगे। मेनू केवल पढ़ने (read-only) के लिए है, इसलिए आप सेटिंग्स फ़ाइल को एडिट करके हुक में बदलाव करते हैं। फ़ाइल वॉचर आमतौर पर बिना रीस्टार्ट किए ही एडिट को पिक कर लेता है।

Claude Code में कौन-से hook events मौजूद हैं

Hooks reference में कुल thirty three events सूचीबद्ध हैं। ये SessionStart से लेकर SessionEnd तक हैं और compaction, subagents, worktrees तथा configuration files को कवर करते हैं। Server work में इनमें से कुछ ही events उपयोग होते हैं।

  • PreToolUse: EndConversation को छोड़कर, किसी tool call के execute होने से पहले। यही वह event है जो execution को block कर सकता है।
  • PostToolUse: EndConversation को छोड़कर, किसी tool call के सफल होने के बाद। Failure होने पर PostToolUseFailure fire होता है। इसलिए हर outcome देखने वाले hook को दोनों की जरूरत होती है।
  • PermissionRequest: जब किसी tool call के लिए permission decision चाहिए। इसी समय approval prompt दिखाई देता।
  • UserPromptSubmit: जब आप prompt submit करते हैं, उससे पहले Claude उसे process करता है। सफल hook का plain-text stdout model के context में जोड़ दिया जाता है।
  • SessionStart और SessionEnd: session के प्रत्येक अंत में। Compaction के बाद SessionStart भी fire होता है, और उस समय matcher value compact होती है।
  • Stop: जब Claude response देना पूरा करता है। यह प्रत्येक turn में एक बार होता है, हर finished task में एक बार नहीं।

जिन events में matchers का support है, उनमें कोई group matcher रख सकता है। यह तय करता है कि किन occurrences पर hook चलेगा। Tool events में यह tool name के आधार पर filter करता है। इसलिए "Edit|Write" केवल file edits पर fire होता है, किसी अन्य घटना पर नहीं। Matchers case sensitive होते हैं। Empty matcher प्रत्येक occurrence पर fire होता है। MCP (model context protocol) server के tools का नाम mcp__<server>__<tool> होता है। इसलिए "mcp__github__.*" matcher किसी एक server के tools को पकड़ता है और बाकी servers को अलग रखता है।

Stop hooks में एक महत्वपूर्ण सावधानी है, जिसे hook लिखने से पहले समझना चाहिए। कोई blocking Stop hook model को दोबारा काम करने के लिए भेजता है। By default, Claude Code लगातार आठ continuations के बाद अगले block को override कर देता है। Claude के किसी tool को call करते ही यह count reset हो जाता है। Hook input से stop_hook_active field पढ़ें और उसके true होने पर exit 0 करें। अन्यथा आपका hook Claude को बार-बार काम करने के लिए भेज सकता है।

हुक stdin पर क्या प्राप्त करता है

जब Claude npm test चलाने वाला होता है, तो Bash पर स्थित एक PreToolUse हुक 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 में startup, resume, clear, compact या fork का एक source मिलता है।

शेल स्क्रिप्ट के भीतर इसे पढ़ने का सामान्य तरीका jq है, और एक न्यूनतम सर्वर इमेज में यह नहीं होता है। इसे पहले Ubuntu और Debian पर sudo apt install -y jq के साथ इंस्टॉल करें।

Exit status का टूल कॉल पर प्रभाव

इसके तीन परिणाम होते हैं।

  • Exit 0 का अर्थ है सफलता, और कोई भी वैध JSON निर्णय फ़ील्ड अभी भी लागू होते हैं, जिसमें ब्लॉक या अस्वीकृति शामिल है। PreToolUse पर, बिना किसी निर्णय के exit 0 का अर्थ स्वीकृति नहीं है, और सामान्य अनुमति प्रवाह (permission flow) अभी भी चलता है। UserPromptSubmit, UserPromptExpansion, SessionStart और PostModelSwitch पर, सादे टेक्स्ट वाला stdout मॉडल के संदर्भ (context) में जोड़ा जाता है। अधिकांश अन्य घटनाओं पर, stdout केवल डिबग लॉग में जाता है।
  • Exit 2 उन घटनाओं पर क्रिया को रोकता है जिन्हें रोका जा सकता है, जिनमें PreToolUse शामिल है, और stderr वह संदेश बन जाता है जो ब्लॉक के साथ आता है, जब तक कि JSON आउटपुट में कोई ब्लॉकिंग निर्णय न हो, जिसका कारण प्राथमिकता लेता है। वह संदेश कौन पढ़ता है, यह घटना पर निर्भर करता है। PreToolUse और Stop पर मॉडल इसे कारण के रूप में देखता है। UserPromptSubmit और PreModelSwitch पर यह आपको दिखाया जाता है और मॉडल के संदर्भ में नहीं जोड़ा जाता है। PostToolUse और PostToolUseFailure पर, जिन्हें रोका नहीं जा सकता, ब्लॉक को अनदेखा कर दिया जाता है, हालांकि stderr अभी भी फीडबैक के रूप में मॉडल तक पहुँचता है। अधिकांश अन्य घटनाओं पर जिन्हें रोका नहीं जा सकता, stderr केवल आपको दिखाया जाता है या अनदेखा कर दिया जाता है। Stop, SubagentStop, TaskCompleted और किसी प्लगइन के UserPromptSubmit हुक पर, खाली stdout और stderr पर missing-file त्रुटि के साथ exit 2 को एक नॉन-ब्लॉकिंग त्रुटि माना जाता है।
  • कोई अन्य exit code सादे टेक्स्ट या खाली stdout के साथ सामान्यतः एक नॉन-ब्लॉकिंग त्रुटि है। ट्रांसक्रिप्ट में Failed with non-blocking status code: टेक्स्ट के बाद stderr की पहली पंक्ति के साथ एक हुक त्रुटि सूचना दिखाई देती है। वैध JSON अभी भी PreToolUse जैसी घटनाओं पर परिणाम तय कर सकता है, जब तक कि हुक की विफलता क्रिया को न रोक दे। WorktreeCreate किसी भी गैर-शून्य (nonzero) exit पर विफल हो जाता है, और WorktreeRemove गैर-शून्य exit पर विफल हो जाता है यदि निर्देशिका (directory) उसके बाद भी मौजूद रहती है।

ब्लॉक करने या चुप रहने के अलावा किसी भी अन्य स्थिति के लिए, exit 0 का उपयोग करें और stdout पर एक JSON ऑब्जेक्ट प्रिंट करें। एक PreToolUse हुक permissionDecision के साथ निर्णय लेता है:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

"allow" इंटरैक्टिव प्रॉम्प्ट को छोड़ देता है जहाँ अनुमति नियम और टूल की स्वीकृति आवश्यकताएं इसकी अनुमति देती हैं, "deny" कॉल को रद्द कर देता है और कारण मॉडल को भेज देता है, और "ask" पुष्टि का अनुरोध करता है। प्रति हुक एक शैली चुनें। exit 2 को stdout पर JSON निर्णय के साथ मिलाने से ब्लॉक बना रहता है, भले ही JSON में "allow" लिखा हो।

जब कई हुक एक ही घटना से मेल खाते हैं, तो वे समानांतर (parallel) चलते हैं, जिसमें प्रॉम्प्ट और एजेंट हुक एक बार में बारह तक सीमित होते हैं। एक हुक से आया deny अपने समकक्षों (siblings) को नहीं रोकता है, इसलिए एक लॉगिंग हुक अपनी लाइन लिखता रहता है जबकि एक गार्डरेल हुक उसी कॉल को अस्वीकार कर देता है। 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"
          }
        ]
      }
    ]
  }
}

स्क्रिप्ट पर भरोसा करने से पहले उसे मैन्युअल रूप से टेस्ट करें, क्योंकि यदि onFailure सेट न हो, तो जो हुक अपने इनपुट पर क्रैश होता है, वह सामान्यतः fail open हो जाता है। Git Bash के बिना Windows पर, एक विफल shell-form PreToolUse या PermissionRequest कमांड हुक टूल कॉल को ब्लॉक कर सकता है:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

आपको stderr पर Blocked by policy: लाइन और 2 का एग्जिट कोड दिखना चाहिए। इसे ls -la जैसी कोई हानिरहित कमांड दें, तो आपको कोई आउटपुट नहीं दिखना चाहिए और एग्जिट कोड 0 होना चाहिए। एक सेशन में, अस्वीकृत कॉल ट्रांसक्रिप्ट में आपके संदेश के साथ कारण के रूप में दिखाई देती है, जिसे मॉडल पढ़कर खुद को अनुकूलित कर लेता है।

एक विशेषता इसे उपयोगी बनाती है: PreToolUse हुक परमिशन-मोड चेक से पहले और हर परमिशन मोड में चलते हैं, इसलिए bypassPermissions के तहत भी अस्वीकृति (deny) प्रभावी रहती है। यही कारण है कि यह हुक Claude Code auto mode और इसकी परमिशन सेटिंग्स के साथ उपयोगी है, जहाँ प्रॉम्प्ट्स को कम कर दिया जाता है लेकिन हुक फिर भी चलता है।

यह क्या है, इसके बारे में स्पष्ट रहें। कमांड स्ट्रिंग पर पैटर्न मैचिंग एक एजेंट की लापरवाही के खिलाफ एक सुरक्षा उपाय (guardrail) है, न कि किसी चतुर एजेंट के खिलाफ कोई सीमा, क्योंकि वही कमांड ऐसे रूप में लिखी जा सकती है जिसे आपका grep कभी देख ही न पाए। कठोर नियम परमिशन सिस्टम और उस अकाउंट में होने चाहिए जिसके तहत प्रोसेस चलती है।

उदाहरण 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
          }
        ]
      }
    ]
  }
}

Claude से किसी Python फाइल में गलत indentation वाला फंक्शन जोड़ने के लिए कहें, फिर फाइल खोलें। यह फॉर्मेट होकर वापस आती है। यह इस बात की जांच है कि हुक चल गया है, क्योंकि एक सफल हुक बातचीत में कुछ भी नहीं दिखाता है।

यहाँ exit 2 किसी भी चीज को undo नहीं करता है। PostToolUse टूल के निष्पादित होने के बाद चलता है, इसलिए संपादन किसी भी स्थिति में डिस्क पर मौजूद रहता है। exit 2 का लाभ यह है कि ruff check आउटपुट फीडबैक के रूप में मॉडल तक पहुँच जाता है, इसलिए यह आगे बढ़ने के बजाय उस त्रुटि को ठीक कर देता है जिसे उसने अभी-अभी पेश किया है। यह उस lint विफलता के बीच का अंतर है जिसे आप commit के समय पाते हैं और जिसे एजेंट उसी टर्न में ठीक कर देता है।

यहाँ दो matcher सीमाएं मायने रखती हैं। Edit|Write शेल कमांड द्वारा बदली गई फाइलों को नहीं देखता है, और Claude अक्सर Bash के माध्यम से फाइलें लिखता है, इसलिए यह अंतर वास्तविक है। प्रति-कॉल कवरेज के लिए, Bash को भी मैच करें और स्क्रिप्ट को git status --porcelain के साथ बदली गई फाइलों की सूची बनाने दें। प्रति-टर्न कवरेज के लिए, स्कैन को Stop हुक में रखें।

उदाहरण 3: audit के लिए हर tool call का log रखें

PostToolUse पर खाली matcher, EndConversation को छोड़कर, हर सफल tool call पर चलता है। Record को home directory की file में भेजने के बजाय system journal में भेजने से वह agent के अपने shell की पहुँच से बाहर नहीं होता। Access account की permissions पर निर्भर करता है। Users अपने private per-user journals पढ़ सकते हैं, और root तथा systemd-journal, adm या wheel के members सभी journal files पढ़ सकते हैं:

{
  "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 से फिर पढ़ें। Records पढ़ने की permission होने पर आपको EndConversation के अलावा हर सफल tool call के लिए एक JSON line दिखनी चाहिए। सबसे नई line अंत में होगी। कुछ भी दिखाई न दे तो journal access और hook के चलने, दोनों की जाँच करें। नीचे troubleshooting section में hook से संबंधित जानकारी है।

असफल calls को capture करने के लिए PostToolUseFailure के नीचे यही block जोड़ें, क्योंकि PostToolUse केवल success पर चलता है और failed command आम तौर पर अधिक महत्वपूर्ण होती है। Home directory की file में append करने के बजाय logger का उपयोग ownership के कारण किया जाता है। Hook agent के shell वाले ही user के रूप में चलता है। इसलिए जिस चीज़ में वह user append कर सकता है, उसे truncate भी कर सकता है। Journal systemd-journald द्वारा लिखा जाता है। फिर भी उसे delete होने से बचाना agent account की privileges पर निर्भर करता है।

Hook कितनी देर तक चल सकता है

चार्टDefault hook timeout in seconds, by hook type and event
इस चार्ट के पीछे का डेटा
[
  {
    "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 मिलते हैं, यानी ten minutes। कुछ events इस समय को काफी कम कर देते हैं। SessionEnd hooks के बीच कुल 1.5 seconds का साझा budget होता है, इसलिए end-of-session cleanup जल्दी पूरा होना चाहिए। हालांकि, settings files में किसी hook पर लंबा timeout सेट करने से यह साझा budget उसी के अनुसार बढ़ जाता है, अधिकतम 60 seconds तक।

यदि कोई synchronous command, HTTP या MCP tool hook अपने timeout तक पहुंच जाता है, तो उसे cancel कर दिया जाता है और आम तौर पर कोई decision render नहीं होता। PreModelSwitch पर timeout switch को block कर देता है। PreToolUse guardrail के मामले में timeout आम तौर पर tool call को सामान्य permission flow में आगे बढ़ने देता है। Windows पर ऊपर बताया गया अपवाद लागू होता है, जब onFailure unset हो। इसी कारण guardrail scripts छोटी रखें। Release 2.1.295 से आप command या http hook पर "onFailure": "block" के साथ यह डिफ़ॉल्ट व्यवहार बदल सकते हैं। इससे timeout, crash या unexpected exit code block में बदल जाता है। इसका कोई प्रभाव Stop, SubagentStop, TaskCompleted, TeammateIdle या background command hooks पर नहीं होता। ऐसे धीमे काम के लिए, जिनके पूरा होने की प्रतीक्षा कोई नहीं कर रहा है, जैसे किसी log को कहीं भेजना, "async": true सेट करें। तब hook background में चलता है और tool call को रोकता नहीं है।

Hooks, rules files, skills और MCP servers

चार चीजें आपस में भ्रमित करती हैं क्योंकि वे सभी agent के व्यवहार को बदलती हैं। उनमें से केवल एक ही ऐसी है जो सुझाव देना बंद कर देती है।

एक rules file (CLAUDE.md, या .claude/rules/ के अंतर्गत कोई file) वह text है जिसे model के context में load किया जाता है। यह व्यवहार को आकार देती है, लेकिन किसी चीज को लागू (enforce) नहीं करती। एक लंबी बातचीत, एक बड़े diff और एक नए user request के सामने, इसकी एक पंक्ति अपना प्रभाव खो सकती है। यही वह सामान्य कारण है जिसके पीछे agents द्वारा आपके द्वारा लिखे गए निर्देशों की अनदेखी करना होता है।

एक skill निर्देशों और scripts का एक folder है जिसे model तब load करता है जब उसे लगता है कि वह skill प्रासंगिक है। वह निर्णय ही skill का मुख्य बिंदु है, और यही इसकी सीमा भी है: निर्णय अभी भी model ही लेता है। आप Ponytail, जो agent को सबसे छोटे प्रभावी बदलाव की ओर धकेलता है जैसी skill में दोनों पहलू देख सकते हैं, क्योंकि यह किसी कार्य के दृष्टिकोण को उस तरह से आकार देती है जैसा कोई hook नहीं कर सकता, और यह केवल तब तक होता है जब तक model इसे load करना चुनता है।

एक MCP (model context protocol) server model को call करने के लिए नए tools देता है। यह agent की पहुँच को बढ़ाता है। यह agent को कुछ भी करने के लिए मजबूर नहीं करता, और यह एक अलग process है जिसे आपको operate करना होता है, जो अपने आप में एक काम है: देखें VPS पर MCP servers चलाना।

इन चारों में hook ही एकमात्र ऐसी चीज है जो model के चुनाव के बिना चलती है। किसी प्राथमिकता (preference) के लिए rules file का उपयोग करें और उस प्रक्रिया (procedure) के लिए skill का उपयोग करें जिसका पालन model को तब करना चाहिए जब वह उसे लागू करे। उस चरण के लिए hook का उपयोग करें जो हर बार होना ही चाहिए, या उस चीज के लिए जो कभी नहीं होनी चाहिए। अधिक विस्तृत तुलना, जिसमें यह भी शामिल है कि कब एक skill, rules file से बेहतर होती है, skills, MCP और rules files की तुलना में दी गई है।

एक plugin पांचवीं कार्यप्रणाली के बजाय एक पैकेजिंग है। यह hooks को skills के साथ एक installable unit में बंडल करता है, जिससे एक टीम हर machine पर एक ही guardrail भेजती है: देखें Claude Code plugins कैसे काम करते हैं।

shared VPS पर सुरक्षा संबंधी निर्णय

hook वह code है जिसे agent trigger करता है, और यह उस user के रूप में चलता है जिसने Claude Code शुरू किया है। यह उस user की file permissions और environment को inherit करता है। laptop पर यह workflow का सवाल है। VPS पर जहाँ agent बिना निगरानी के चलता है, यह चार व्यावहारिक पहलुओं वाला सुरक्षा का सवाल है।

repository में मौजूद hook वह code है जिसे आपने नहीं लिखा है। .claude/settings.json commit किया जाता है, इसलिए repository को clone करना और उसके अंदर session शुरू करने से वे hooks register हो सकते हैं जो repository के साथ आए थे। interactive session में, Claude Code उस folder के लिए workspace trust dialog के पीछे project hooks को रोकता है, जिसका अर्थ है कि trust स्वीकार करना ही वह क्षण है जब आप उन्हें चलाने का निर्णय लेते हैं। पहले hooks block को पढ़ें। claude -p या SDK session, जो कि unattended agent के चलने का सामान्य तरीका है, कभी वह dialog नहीं दिखाता और folder को trusted मानता है, इसलिए repository के hooks बिना पूछे चल जाते हैं। इसके खिलाफ script बनाने से पहले इसकी .claude/ files की समीक्षा करें, या --settings '{"disableAllHooks": true}' के साथ चलाएं।

hook पूरा tool input देख सकता है। एक audit hook जो tool_input को log करता है, हर command के हर argument को log में लिखता है, जिसमें command line पर मौजूद कोई भी token शामिल हो सकता है। उस log को फिर उसी सुरक्षा की आवश्यकता होती है जिसकी secret को है, जो AI agent की पहुँच से secrets को दूर रखने की व्यापक समस्या का हिस्सा है।

hook model के context में लिख सकता है। सफल SessionStart या UserPromptSubmit hook से प्राप्त plain-text stdout को conversation में जोड़ दिया जाता है। एक hook जो बाहर से, issue tracker या log file से text pipe करता है, वह model को untrusted text ऐसे सौंप रहा है जैसे आपने खुद उसे टाइप किया हो। एक hook जो उसी VPS पर किसी अन्य Claude Code session से note forward करता है, वह भी यही कर रहा है, और एक agent के output का आपके भरोसे पर issue tracker से अधिक दावा नहीं है। उस stdout को output के बजाय input की तरह मानें।

Privilege ही वास्तविक नियंत्रण है। agent को एक समर्पित unprivileged user के रूप में चलाएं जिसे केवल आवश्यक sudo rules प्राप्त हों। PreToolUse deny का होना फायदेमंद है, और यह design के अनुसार best effort है: reference में if filter के बारे में भी यही कहा गया है और आपको सलाह दी जाती है कि जब आपको hard deny की आवश्यकता हो तो permission system का उपयोग करें। permission rules और वह account जिसके तहत process चलती है, वही हिस्से हैं जो दबाव में टिके रहते हैं।

एक गुण हर permission mode में काम करता है। PreToolUse hooks हर permission mode में permission-mode check से पहले चलते हैं, इसलिए deny लौटाने वाला hook bypassPermissions के तहत भी tool को block कर देता है। hooks permission rules द्वारा दी गई अनुमति को सीमित कर सकते हैं। वे उसे ढीला नहीं कर सकते। अपवाद एक mod है। बिना managed settings और बिना managed-mcp.json file वाली मशीन पर, ऐसे session में जो Team या Enterprise plan के लिए /login के माध्यम से signed in नहीं है, tool.check को संभालने वाला एक installed mod उस call को approve कर सकता है जिसे आपके PreToolUse hook ने block किया था। managed settings, managed-mcp.json file, या session के credential के रूप में Team या Enterprise /login के साथ, जिस call को PreToolUse hook ने block किया है, वह डिफ़ॉल्ट रूप से block ही रहती है, चाहे hook किसी भी settings file से आया हो। API key या long-lived CLAUDE_CODE_OAUTH_TOKEN पर चलने वाला session, जो कि कई servers पर चलाने का तरीका है, signed in न होने के रूप में गिना जाता है, भले ही login stored हो। server पर install करने से पहले जांच लें कि Claude Code mods क्या बदल सकते हैं।

मेरा हुक (hook) ट्रिगर क्यों नहीं हो रहा है?

इसे क्रमवार तरीके से जाँचें। प्रत्येक चरण में वह लक्षण बताया गया है जो आपको वास्तव में दिखाई देगा।

  • /hooks चलाएँ और देखें कि क्या हुक आपकी अपेक्षित घटना (event) के अंतर्गत दिखाई दे रहा है। यदि मेनू में हुक गायब है, तो इसका मतलब आमतौर पर यह है कि सेटिंग्स फ़ाइल में JSON सिंटैक्स त्रुटि है, क्योंकि इसमें ट्रेलिंग कॉमा (trailing commas) और टिप्पणियों (comments) की अनुमति नहीं है, या फ़ाइल ऊपर बताए गए छह स्थानों में से किसी में भी नहीं है।
  • मैचर (matcher) की तुलना टूल के नाम से बिल्कुल सटीक रूप से करें। मैचर्स केस-सेंसिटिव होते हैं, इसलिए "bash" कभी भी Bash टूल से मेल नहीं खाएगा।
  • स्क्रिप्ट को मैन्युअल रूप से सैंपल इनपुट के साथ चलाएँ, जैसा कि ऊपर उदाहरण 1 में दिया गया है। यदि एग्जिट कोड आपकी अपेक्षा के अनुरूप नहीं है, तो यह आपकी स्क्रिप्ट में बग है; इसके stdout की भी जाँच करें, क्योंकि वैध JSON भी PreToolUse जैसी घटनाओं पर निर्णय प्रदान कर सकता है।
  • jq: command not found का नोटिस मिलने का मतलब है कि उस मशीन पर jq मौजूद नहीं है। आपकी अपनी स्क्रिप्ट के लिए command not found का मतलब है कि पाथ (path) रिजॉल्व नहीं हुआ, इसलिए ${CLAUDE_PROJECT_DIR} या एब्सोल्यूट पाथ का उपयोग करें। यदि स्क्रिप्ट बिल्कुल भी नहीं चलती है, तो संभवतः वह एक्जीक्यूटेबल (executable) नहीं है।
  • हुक वैध JSON प्रिंट करता है लेकिन कुछ नहीं होता है। macOS और Linux पर, शेल-फॉर्म हुक एक नॉन-इंटरैक्टिव शेल में sh -c के माध्यम से चलता है, लेकिन कुछ सेटअप अभी भी आपकी प्रोफ़ाइल को सोर्स (source) करते हैं, जैसे कि BASH_ENV का ~/.bashrc पर पॉइंट करना। यदि वह प्रोफ़ाइल कोई बैनर प्रिंट करती है, तो वह बैनर आपके JSON के आगे जुड़ जाता है। Stdout अब { से शुरू नहीं होता है, इसलिए Claude Code पूरी चीज़ को प्लेन टेक्स्ट के रूप में पढ़ता है और निर्णय को अनदेखा कर देता है। चूंकि हुक 0 के साथ एग्जिट हुआ, इसलिए ट्रांसक्रिप्ट में कोई त्रुटि नहीं दिखाई देती है। अधिकांश घटनाओं पर वह टेक्स्ट केवल डिबग लॉग में जाता है, जबकि UserPromptSubmit, UserPromptExpansion, SessionStart और PostModelSwitch पर इसे बैनर सहित मॉडल के कॉन्टेक्स्ट में जोड़ दिया जाता है। अपनी प्रोफ़ाइल में किसी भी echo को रैप (wrap) करें ताकि वह केवल इंटरैक्टिव शेल में ही चले।
  • यदि अभी भी समस्या बनी हुई है: सेशन को claude --debug-file /tmp/claude.log के साथ शुरू करें और दूसरे टर्मिनल में tail -f /tmp/claude.log चलाएँ। डिबग लॉग यह रिकॉर्ड करता है कि कौन से हुक मैच हुए, प्रत्येक ने क्या एग्जिट कोड लौटाया, और उन्होंने stdout और stderr पर क्या लिखा।

FAQ

Claude Code hook और CLAUDE.md instruction के बीच क्या अंतर है?

एक CLAUDE.md instruction मॉडल के context में मौजूद टेक्स्ट होता है, इसलिए यह conversation और वर्तमान request के साथ ध्यान आकर्षित करने के लिए प्रतिस्पर्धा करता है, और मॉडल इसे उनके मुकाबले तौल सकता है। एक hook एक shell command है जिसे Claude Code अपने lifecycle के एक निश्चित बिंदु पर चलाता है, इसलिए यह मॉडल के निर्णय की परवाह किए बिना हर बार उस event के होने पर निष्पादित होता है। किसी प्राथमिकता (preference) के लिए instruction का उपयोग करें। ऐसे चरण के लिए hook का उपयोग करें जिसे हमेशा होना चाहिए या ऐसी कार्रवाई के लिए जिसे कभी नहीं होना चाहिए।

मैं Claude Code को एक विशिष्ट shell command चलाने से कैसे रोकूँ?

एक PreToolUse hook को Bash matcher के साथ रजिस्टर करें जो .tool_input.command से command को पढ़ता है, stderr पर एक कारण लिखता है और 2 के साथ exit करता है। Claude Code कॉल को रद्द कर देता है और मॉडल को आपका कारण दिखाता है, और यह permission-mode चेक से पहले होता है, इसलिए यह deny bypassPermissions मोड में भी प्रभावी रहता है। command string पर pattern matching एक सुरक्षा सीमा (security boundary) के बजाय एक guardrail है, क्योंकि उसी command को ऐसे रूप में लिखा जा सकता है जिसे pattern न पहचान पाए, इसलिए इसे permission rules और एक unprivileged account के साथ सुरक्षित करें।

मेरा hook वैध JSON प्रिंट करता है लेकिन कुछ नहीं होता। क्यों?

JSON से पहले प्रिंट किए गए टेक्स्ट के लिए अपनी shell profile की जाँच करें। macOS और Linux पर, बिना args field वाला hook sh -c के माध्यम से चलता है, और उन setups में जो अभी भी आपकी profile को source करते हैं, जैसे कि BASH_ENV जो ~/.bashrc की ओर इशारा करता है, एक profile जो banner प्रिंट करती है, वह आपके JSON से पहले stdout पर उसे डाल देती है। क्योंकि output अब { से शुरू नहीं होता है, Claude Code इसे plain text मानता है और निर्णय को अनदेखा कर देता है, और क्योंकि hook 0 के साथ exit हुआ, transcript में कोई error नहीं दिखता है। अपनी profile में किसी भी echo को interactive-shell test के साथ सुरक्षित करें, फिर claude --debug-file /tmp/claude.log से debug log पढ़कर सुधार की पुष्टि करें।

क्या shared server पर Claude Code hooks चलाना सुरक्षित है?

Hooks उस user के रूप में चलते हैं जिसने Claude Code शुरू किया है, उस user की file permissions के साथ, इसलिए एक hook वह सब कुछ कर सकता है जो वह account कर सकता है। दो आदतें अधिकांश जोखिम को कवर करती हैं: agent को एक सीमित sudo policy वाले समर्पित unprivileged account के रूप में चलाएं, और किसी भी repository के hooks block को पढ़ें, इससे पहले कि आप उसके workspace trust dialog को स्वीकार करें या उसमें claude -p चलाएं, क्योंकि project hooks .claude/settings.json के अंदर आते हैं और -p मोड वह dialog कभी नहीं दिखाता है। Hooks को अक्षम करने के लिए अपनी settings file में "disableAllHooks": true सेट करें, सिवाय उन managed hooks के जिन्हें managed स्तर पर सेटिंग की आवश्यकता होती है; false की project setting, true की user setting को ओवरराइड कर सकती है।

क्या यह लेख उपयोगी था?