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 मधील instruction हा सल्ला असतो. Model आपल्या context मधील इतर सर्व माहितीच्या तुलनेत त्याचा विचार करते. Hook हा code असतो. Model सहमत असो वा नसो, तो code चालतो. तुम्ही formatter बद्दल दोनदा सांगूनही तुमचा agent तो सतत वगळत असेल, तर अधिक कडक instruction आवश्यक नाही. तुम्हाला hook आवश्यक आहे.

ही यंत्रणा लहान आहे. तुम्ही settings file मध्ये event name अंतर्गत command नोंदवता. तो event घडल्यावर 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 छापला असेल, तर त्यातील reason ला प्राधान्य मिळते.

येथील event names आणि field names हे Claude Code hooks reference मधून घेतले आहेत. ही reference November 12, 2026 रोजी तपासली होती. हा भाग जलद बदलतो. त्यामुळे या लेखासह कोणत्याही blog post मधून JSON कॉपी करण्यापूर्वी तुमच्या स्वतःच्या version साठीची reference तपासा. तुमची reference claude --version ने छापा.

हुक configuration कुठे असते

हुक हा settings file मधील JSON block असतो. सहा ठिकाणी हुक ठेवता येतो. त्या file ची scope म्हणजेच त्या हुकची scope असते.

  • ~/.claude/settings.json: तुमच्या मशीनवरील प्रत्येक project साठी. इतर कोणाच्याही project साठी नाही.
  • .claude/settings.json: एका project साठी. तो repository मध्ये commit केलेला असतो, त्यामुळे repository clone करणाऱ्या प्रत्येकाला हा हुक मिळतो.
  • .claude/settings.local.json: एका project साठी. तो फक्त तुमच्या मशीनवर लागू असतो.
  • Managed policy settings: संपूर्ण organisation साठी. हे administrator सेट करतो.
  • Plugin मधील hooks/hooks.json: तो plugin enabled असेपर्यंत लागू असतो.
  • Skill किंवा subagent frontmatter. Skill invoke केल्यानंतर त्या session च्या उर्वरित कालावधीत त्या skill चे hooks लागू राहतात. Subagent चालू असेपर्यंत त्याचे hooks लागू राहतात.

या files मधील hook entries एकमेकांना override न करता merge होतात. Project settings file तुमच्या user settings मधील hooks बदलत नाही; ती त्यात स्वतःचे hooks जोडते. त्यामुळे एका event मध्ये अनेक files मधील अनेक hooks असू शकतात. "disableAllHooks": true सेट केल्यास हे hooks बंद होतात. मात्र एक अपवाद आहे: managed policy settings मधील hooks सुरूच राहतात, जोपर्यंत ते setting managed settings मध्येही लागू केले जात नाही.

सध्या registered असलेले सर्व hooks event नुसार पाहण्यासाठी session मध्ये /hooks चालवा. प्रत्येक hook साठी source file आणि matcher देखील दाखवला जातो. हा menu read-only आहे. त्यामुळे hook बदलण्यासाठी settings file संपादित करा. File watcher साधारणपणे restart न करता केलेला बदल ओळखतो.

Claude Code मध्ये कोणते hook events उपलब्ध आहेत

hooks reference मध्ये SessionStart पासून SessionEnd पर्यंत एकूण तेहतीस events दिले आहेत. त्यामध्ये compaction, subagents, worktrees आणि configuration files यांचा समावेश आहे. Server work साठी त्यांपैकी काही events पुरेसे असतात.

  • PreToolUse: EndConversation वगळता, tool call execute होण्यापूर्वी. हा event execution थांबवू शकतो.
  • PostToolUse: EndConversation वगळता, tool call यशस्वी झाल्यानंतर. Tool call अयशस्वी झाल्यावर त्याऐवजी PostToolUseFailure चालतो. त्यामुळे प्रत्येक परिणाम पाहणाऱ्या hook साठी दोन्ही events आवश्यक आहेत.
  • PermissionRequest: tool call साठी permission decision आवश्यक असताना. याच वेळी approval prompt दिसतो.
  • UserPromptSubmit: prompt submit केल्यानंतर, Claude त्यावर प्रक्रिया करण्यापूर्वी. यशस्वी hook चा plain-text stdout model च्या context मध्ये जोडला जातो.
  • SessionStart आणि SessionEnd: session संपताना आणि सुरू होताना. Compaction नंतर SessionStart देखील चालतो, आणि त्यासाठी matcher value compact असते.
  • Stop: Claude चे उत्तर पूर्ण झाल्यावर. हा प्रत्येक turn साठी एकदा चालतो; पूर्ण झालेल्या task साठी एकदा चालत नाही.

Matchers समर्थित असलेल्या events मध्ये, एखादा group matcher बाळगू शकतो. त्यावरून कोणत्या occurrences वेळी hook चालवायचा हे ठरते. Tool events मध्ये matcher tool name नुसार filter करतो. त्यामुळे "Edit|Write" file edits वर चालतो आणि इतर कोणत्याही गोष्टीवर चालत नाही. Matchers case sensitive असतात. रिकामा matcher प्रत्येक occurrence वर चालतो. MCP (model context protocol) server कडील tools ची नावे mcp__<server>__<tool> अशा स्वरूपात असतात. त्यामुळे "mcp__github__.*" matcher वापरल्यास एका server ची tools निवडली जातात आणि इतर tools वगळल्या जातात.

Stop hooks मध्ये एक महत्त्वाचा धोका आहे. तो hook लिहिण्यापूर्वी तो समजून घ्या. Claude Code ला काम सुरू ठेवण्यास सांगणारा Stop hook model ला पुन्हा कामाकडे पाठवतो. सलग आठ continuations नंतर Claude Code पुढील block वर default ने override करतो. Claude एखादा tool call करतो तेव्हा ही संख्या पुन्हा शून्य होते. Hook input मधील stop_hook_active field वाचा आणि त्याची value 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 fields मध्ये session_id, cwd, transcript_path आणि hook_event_name यांचा समावेश असतो; permission_mode प्रत्येक event वेळी पाठवले जात नाही. Tool events मध्ये tool_name, tool_input आणि tool_use_id ही fields जोडली जातात. इतर events मध्ये त्यांच्या स्वतःच्या fields असतात: UserPromptSubmit मध्ये prompt मजकूर मिळतो, तर 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 fields असल्यास ते लागू होतात; त्यात block किंवा denial देखील असू शकतो. PreToolUse वर, decision शिवाय exit 0 म्हणजे approval नाही. सामान्य permission flow तरीही सुरू राहतो. UserPromptSubmit, UserPromptExpansion, SessionStart आणि PostModelSwitch वर plain-text stdout model च्या context मध्ये जोडला जातो. इतर बहुतेक events वर stdout फक्त debug log मध्ये जातो.
  • Exit 2 हा block करता येणाऱ्या events वर action block करतो; त्यात PreToolUse देखील येतो. JSON output मध्ये blocking decision असल्यास त्याचा reason प्राधान्याने वापरला जातो; अन्यथा stderr मधील संदेश block सोबत दाखवला जातो. तो संदेश कोण वाचतो हे event वर अवलंबून असते. PreToolUse आणि Stop वर model तो reason म्हणून पाहतो. UserPromptSubmit आणि PreModelSwitch वर तो तुम्हाला दाखवला जातो आणि model च्या context मध्ये जोडला जात नाही. PostToolUse आणि PostToolUseFailure यांना block करता येत नाही; त्यामुळे block दुर्लक्षित केला जातो, परंतु stderr feedback म्हणून model पर्यंत पोहोचतो. block करता न येणाऱ्या इतर बहुतेक events वर stderr फक्त तुम्हाला दाखवला जातो किंवा दुर्लक्षित केला जातो. Stop, SubagentStop, TaskCompleted आणि plugin च्या UserPromptSubmit hook वर, empty stdout आणि stderr वर missing-file error असलेला exit 2 हा non-blocking error मानला जातो.
  • इतर कोणताही exit code आणि plain-text किंवा empty stdout असल्यास तो सामान्यतः non-blocking error असतो. Transcript मध्ये Failed with non-blocking status code: या मजकुरानंतर stderr मधील पहिली ओळ असलेली hook error सूचना दिसते. PreToolUse सारख्या events वर valid JSON तरीही outcome ठरवू शकतो, जोपर्यंत hook चे अपयश action block करत नाही. WorktreeCreate कोणत्याही nonzero exit वर fail होते. Directory नंतरही अस्तित्वात असल्यास WorktreeRemove nonzero exit वर fail होते.

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."
  }
}

Permission rules आणि tool च्या approval requirements मुळे परवानगी असल्यास "allow" interactive prompt वगळतो. "deny" call रद्द करून reason model कडे पाठवतो. "ask" confirmation मागतो. प्रत्येक hook साठी एकच style निवडा. stdout वर JSON decision देताना exit 2 वापरल्यास block कायम राहतो, JSON मध्ये "allow" असले तरी.

एका event शी अनेक hooks जुळल्यास ते parallel चालतात. Prompt आणि agent hooks एकाच वेळी जास्तीत जास्त twelve hooks पर्यंत चालतात. एका hook कडील deny मुळे त्याचे sibling hooks थांबत नाहीत. त्यामुळे guardrail hook त्याच call ला deny करत असतानाही logging hook आपली ओळ लिहितो. PreToolUse साठी Claude Code नंतर सर्व answers merge करतो आणि deny, defer, ask, allow या क्रमाने सर्वाधिक restrictive निर्णय ठेवतो.

उदाहरण 1: विध्वंसक command सुरू होण्यापूर्वी तो अवरोधित करा

हे तुमच्या 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"
          }
        ]
      }
    ]
  }
}

या script वर विश्वास ठेवण्यापूर्वी तो स्वतः चालवून तपासा. कारण hook स्वतःच्या input वर crash झाला आणि onFailure unset असेल, तर तो साधारणपणे 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 दिसू नये आणि 0 exit code दिसला पाहिजे. Session मध्ये denied call transcript मध्ये तुमच्या message ला कारण म्हणून दाखवला जातो. Model ते message वाचून पुढील कृतीत बदल करतो.

एक गुणधर्म हे करण्यास उपयुक्त ठरवतो: PreToolUse hooks permission-mode तपासणीपूर्वी, प्रत्येक permission mode मध्ये चालतात. त्यामुळे bypassPermissions अंतर्गतही deny लागू राहतो. त्यामुळे Claude Code auto mode आणि त्याच्या permission settings सोबत hook उपयुक्त ठरतो. अशा वेळी prompts कमी केलेले असले तरी hook तरीही चालतो.

याची मर्यादा स्पष्टपणे समजून घ्या. command string वर pattern matching करणे म्हणजे agent ने निष्काळजीपणे वागू नये यासाठीचा guardrail आहे. तो agent हुशारीने नियम चुकवण्यापासून संरक्षण करणारी boundary नाही. कारण तीच command तुमच्या grep ला न दिसणाऱ्या पद्धतीने लिहिता येते. कठोर नियम permission system मध्ये आणि process ज्या account अंतर्गत चालतो त्या account मध्ये ठेवले पाहिजेत.

उदाहरण 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 फाइलमध्ये चुकीच्या indentation असलेले function जोडण्यास सांगा आणि नंतर ती फाइल उघडा. फाइल formatted दिसते. Hook चालला याची हीच पडताळणी आहे, कारण hook यशस्वी झाल्यावर संभाषणात काहीही दिसत नाही.

येथील exit 2 कोणताही बदल मागे घेत नाही. PostToolUse tool आधीच execute झाल्यानंतर चालतो, त्यामुळे edit कोणत्याही परिस्थितीत disk वर जतन झालेला असतो. exit 2 मुळे ruff check चे output model कडे feedback म्हणून पोहोचते. त्यामुळे model पुढे जाण्याऐवजी नुकतीच निर्माण केलेली error दुरुस्त करतो. Commit वेळी आढळणारा lint failure आणि त्याच turn मध्ये agent ने दुरुस्त केलेली lint failure यातील हा फरक आहे.

येथे दोन matcher मर्यादा महत्त्वाच्या आहेत. Shell command मुळे बदललेल्या फाइल्स Edit|Write ला दिसत नाहीत. तसेच Claude पुरेशा वेळा Bash द्वारे फाइल्स लिहितो, त्यामुळे ही उणीव प्रत्यक्षात येते. प्रत्येक call साठी coverage हवी असल्यास Bash शी देखील match करा आणि script कडून बदललेल्या फाइल्स git status --porcelain सह सूचीबद्ध करून घ्या. प्रत्येक turn मध्ये एकदाच coverage हवी असल्यास scan Stop hook मध्ये ठेवा.

उदाहरण 3: audit साठी प्रत्येक tool call ची नोंद करा

PostToolUse वरील रिकामे matcher EndConversation वगळता प्रत्येक यशस्वी tool call वर कार्यान्वित होते. नोंद home directory मधील file ऐवजी system journal मध्ये पाठवली तरी ती agent च्या स्वतःच्या shell पासून लपून राहत नाही. प्रवेश 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 दिसली पाहिजे; सर्वात नवीन नोंद शेवटी असते. काहीही दिसत नसल्यास journal access आणि hook चालला आहे का हे दोन्ही तपासा. खालील troubleshooting section मध्ये hook विषयी माहिती आहे.

अयशस्वी calls ची नोंद करण्यासाठी PostToolUseFailure खाली हाच block जोडा. PostToolUse केवळ यशस्वी calls वर कार्यान्वित होते, आणि अयशस्वी command बहुतेकदा अधिक महत्त्वाचा असतो. home directory मधील file ला append करण्याऐवजी logger वापरण्याचे कारण ownership आहे. Hook agent च्या shell प्रमाणेच त्याच user म्हणून चालतो. त्यामुळे एखादा user ज्या file मध्ये append करू शकतो, ती file truncate देखील करू शकतो. Journal systemd-journald द्वारे लिहिला जातो. मात्र तो delete होण्यापासून सुरक्षित राहील का हे agent account च्या privileges वरच अवलंबून असते.

हुक किती वेळ चालू शकतो

तक्ता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 सेकंद चालू शकतो. हा कालावधी दहा मिनिटांचा आहे. काही events हा कालावधी मोठ्या प्रमाणात कमी करतात. SessionEnd hooks या सर्वांसाठी मिळून 1.5 सेकंदांचा budget share करतात. त्यामुळे end-of-session cleanup त्वरेने पूर्ण करणे आवश्यक असते. मात्र settings files मधील एखाद्या hook साठी मोठे timeout सेट केल्यास हा shared budget त्यानुसार वाढतो. त्याची कमाल मर्यादा 60 सेकंद आहे.

Timeout गाठणारा synchronous command, HTTP किंवा MCP tool hook रद्द केला जातो आणि सामान्यतः कोणताही decision तयार होत नाही. PreModelSwitch वर timeout switch ला block करतो. PreToolUse guardrail साठी timeout मुळे tool call सामान्य permission flow मध्ये पुढे जाण्याची परवानगी मिळते. मात्र onFailure unset असल्यास वर नमूद केलेला Windows अपवाद लागू होतो. त्यामुळे guardrail scripts लहान ठेवा. Release 2.1.295 पासून command किंवा http hook वर "onFailure": "block" वापरून हा default बदलता येतो. यामुळे timeout, crash किंवा अनपेक्षित exit code आल्यास block केला जातो. मात्र याचा Stop, SubagentStop, TaskCompleted, TeammateIdle किंवा background command hooks वर परिणाम होत नाही. कोणाचीही प्रतीक्षा आवश्यक नसलेल्या slow work साठी, उदाहरणार्थ log कुठेतरी पाठवण्यासाठी, "async": true सेट करा. अशा वेळी tool call थांबविल्याशिवाय hook background मध्ये चालतो.

Hooks, rules files, skills आणि MCP servers

चार गोष्टी एकमेकांशी गोंधळल्या जातात कारण त्या सर्व एजंटचे कार्य बदलतात. त्यापैकी फक्त एक गोष्ट सूचनेच्या पलीकडे जाऊन अनिवार्य ठरते.

एक rules file (CLAUDE.md, किंवा .claude/rules/ अंतर्गत असलेली फाईल) म्हणजे मॉडेलच्या कॉन्टेक्स्टमध्ये लोड केलेला मजकूर असतो. हे वर्तनाला आकार देते, परंतु कशाचीही सक्ती करत नाही. प्रदीर्घ संभाषण, मोठा diff आणि नवीन वापरकर्ता विनंती यांच्या तुलनेत, यातील एक ओळ दुर्लक्षित होऊ शकते. एजंटने तुम्ही लिहिलेल्या सूचनांकडे दुर्लक्ष करणे यामागील हेच सामान्य कारण आहे.

Skill म्हणजे सूचना आणि स्क्रिप्ट्सचा एक फोल्डर, जो मॉडेलला जेव्हा एखादी skill संबंधित वाटते तेव्हा ते लोड करते. तो निर्णय घेणे हाच skill चा मुख्य उद्देश आहे आणि तीच त्याची मर्यादा देखील आहे: शेवटी मॉडेलच निर्णय घेते. तुम्ही Ponytail सारख्या skill मध्ये दोन्ही बाजू पाहू शकता, जी एजंटला सर्वात लहान आणि प्रभावी बदलाकडे प्रवृत्त करते. हे एखाद्या कार्याकडे पाहण्याचा दृष्टिकोन अशा प्रकारे आकारते जो कोणत्याही hook ला शक्य नाही, आणि हे फक्त तेव्हाच घडते जेव्हा मॉडेल ती skill लोड करण्याचे निवडते.

MCP (model context protocol) server मॉडेलला कॉल करण्यासाठी नवीन टूल्स उपलब्ध करून देतो. हे एजंटची पोहोच वाढवते. हे एजंटला कशाचाही वापर करण्यास भाग पाडत नाही आणि ही एक स्वतंत्र प्रक्रिया आहे जी तुम्हाला चालवावी लागते, जे स्वतःच एक काम आहे: VPS वर MCP servers चालवणे पहा.

या चार गोष्टींपैकी hook हा एकमेव असा प्रकार आहे जो मॉडेलच्या निवडीशिवाय कार्यान्वित होतो. पसंती दर्शवण्यासाठी rules file चा वापर करा आणि जेव्हा मॉडेलला एखादी प्रक्रिया लागू करायची असेल तेव्हा skill चा वापर करा. ज्या पायऱ्या प्रत्येक वेळी घडणे आवश्यक आहे किंवा ज्या गोष्टी कधीही घडू नयेत, त्यासाठी hook चा वापर करा. skill हे rules file पेक्षा कधी सरस ठरते, यासह सखोल तुलना skills, MCP आणि rules files ची तुलना मध्ये दिली आहे.

Plugin ही पाचवी यंत्रणा नसून ती एक पॅकेजिंग पद्धत आहे. हे hooks आणि skills यांना एकत्र करून एक इन्स्टॉल करण्यायोग्य युनिट बनवते, ज्याद्वारे एखादी टीम प्रत्येक मशीनवर समान सुरक्षा नियम (guardrail) लागू करते: Claude Code plugins कसे काम करतात पहा.

सामायिक VPS वरील security निर्णय

Hook हा agent ने trigger केलेला code असतो आणि Claude Code सुरू करणाऱ्या user म्हणूनच तो चालतो. त्या user च्या file permissions आणि environment चा त्याला वारसा मिळतो. Laptop वर हा workflow संबंधी प्रश्न असतो. Unattended agent चालणाऱ्या VPS वर हा चार व्यावहारिक भाग असलेला security प्रश्न असतो.

Repository मधील hook हा तुम्ही लिहिलेला नसलेला code असतो. .claude/settings.json commit केलेले असते. त्यामुळे repository clone करून त्यामध्ये session सुरू केल्यास repository सोबत आलेले hooks नोंदवले जाऊ शकतात. Interactive session मध्ये Claude Code त्या folder साठी workspace trust dialog मागे project hooks चालवते. म्हणजे trust स्वीकारणे हा ते hooks चालवण्याचा निर्णय घेण्याचा क्षण असतो. आधी hooks block वाचा. claude -p किंवा SDK session मध्ये, ज्याप्रकारे unattended agent सहसा चालतो, हा dialog कधीही दाखवला जात नाही आणि folder trusted मानला जातो. त्यामुळे repository चे hooks विचारणा न करता चालतात. त्यावर script करण्यापूर्वी त्यातील .claude/ files तपासा किंवा --settings '{"disableAllHooks": true}' सह चालवा.

Hook ला संपूर्ण tool input दिसतो. tool_input log करणारा audit hook प्रत्येक command चा प्रत्येक argument log मध्ये लिहितो. त्यात command line वर योगायोगाने आलेला कोणताही token समाविष्ट असू शकतो. त्या log ला secret इतकेच protection आवश्यक असते. हे AI agent च्या आवाक्याबाहेर secrets ठेवण्याच्या व्यापक समस्येचा भाग आहे.

Hook model च्या context मध्ये लिहू शकतो. यशस्वी SessionStart किंवा UserPromptSubmit hook कडून आलेला plain-text stdout conversation मध्ये जोडला जातो. बाहेरील स्रोत, issue tracker किंवा log file मधील मजकूर pipe करणारा hook, तो मजकूर तुम्ही स्वतः type केल्याप्रमाणे model कडे पाठवतो. त्याच VPS वरील दुसऱ्या Claude Code session मधून note forward करणारा hook देखील तेच करतो. एका agent च्या output वर issue tracker च्या output पेक्षा अधिक विश्वास ठेवण्याचे कारण नाही. त्या stdout कडे output म्हणून नव्हे, तर input म्हणून पाहा.

Privilege हेच खरे नियंत्रण आहे. Agent ला स्वतंत्र unprivileged user म्हणून चालवा आणि त्याला आवश्यक तेवढेच sudo rules द्या. PreToolUse deny उपयुक्त आहे. मात्र ते design नुसार best effort असते. Reference मध्ये if filter बाबतही हेच सांगितले आहे आणि hard deny आवश्यक असल्यास permission system वापरण्यास सांगितले आहे. Permission rules आणि process ज्या account अंतर्गत चालतो ते account हेच दबावाच्या परिस्थितीत लागू राहणारे भाग आहेत.

प्रत्येक permission mode मध्ये एक गुणधर्म कायम लागू असतो. प्रत्येक permission mode मध्ये PreToolUse hooks permission-mode check च्या आधी चालतात. त्यामुळे deny परत करणारा hook bypassPermissions अंतर्गतही tool block करतो. Hooks permission rules ने परवानगी दिलेल्या गोष्टी अधिक मर्यादित करू शकतात. ते त्या मर्यादा शिथिल करू शकत नाहीत. Mod हा अपवाद आहे. Managed settings नसलेल्या machine वर, managed-mcp.json file नसलेल्या session मध्ये आणि /login द्वारे Team किंवा Enterprise plan मध्ये sign in न केलेले असताना, tool.check हाताळणारा installed mod तुमच्या PreToolUse hook ने block केलेला call approve करू शकतो. Managed settings, managed-mcp.json file किंवा session चे credential म्हणून Team किंवा Enterprise /login असल्यास, PreToolUse hook ने block केलेला call default नुसार blockच राहतो. Hook कोणत्या settings file मधून आला आहे याने फरक पडत नाही. API key किंवा दीर्घकाळ वापरला जाणारा CLAUDE_CODE_OAUTH_TOKEN वापरून चालणारे session, जसे अनेक servers वर चालतात, sign in केलेले मानले जात नाहीत. Login stored असला तरी हेच लागू होते. Server वर mod install करण्यापूर्वी Claude Code mods मध्ये कोणते बदल करू शकतात ते तपासा.

माझा hook का चालत नाही?

ही प्रक्रिया दिलेल्या क्रमाने करा. प्रत्येक चरणात प्रत्यक्ष दिसणारे लक्षण नमूद केले आहे.

  • /hooks चालवा आणि अपेक्षित event अंतर्गत hook दिसत आहे का ते तपासा. मेनूमध्ये hook दिसत नसेल, तर settings file मध्ये JSON syntax error असण्याची शक्यता असते, कारण trailing commas आणि comments अनुमत नाहीत. तसेच file वरील सहा स्थानांपैकी एखाद्या ठिकाणी आहे का ते तपासा.
  • Matcher ची tool name शी तंतोतंत तुलना करा. Matchers case-sensitive असतात. त्यामुळे "bash" हा Bash tool शी कधीही match होत नाही.
  • वरील example 1 प्रमाणे sample input देऊन script manually चालवा. अपेक्षेप्रमाणे नसलेला exit code तुमच्या script मधील bug दर्शवतो. त्याचे stdout देखील तपासा, कारण वैध JSON मुळे PreToolUse सारख्या events वर निर्णय दिला जाऊ शकतो.
  • jq: command not found असा notice दिसत असल्यास, त्या machine वर jq उपलब्ध नाही. तुमच्या स्वतःच्या script साठी command not found दिसत असल्यास path resolve झालेला नाही. त्यामुळे ${CLAUDE_PROJECT_DIR} किंवा absolute path वापरा. Script अजिबात चालत नसेल, तर तो executable नसण्याची शक्यता आहे.
  • Hook वैध JSON print करतो, पण काहीही घडत नाही. macOS आणि Linux वर shell-form hook non-interactive shell मध्ये sh -c द्वारे चालतो. तरीही काही setups तुमचा profile source करतात; उदाहरणार्थ, BASH_ENV हा ~/.bashrc कडे निर्देश करत असल्यास. त्या profile मधून banner print होत असल्यास, तो तुमच्या JSON च्या सुरुवातीला जोडला जातो. त्यामुळे stdout ची सुरुवात { ने होत नाही. Claude Code संपूर्ण output plain text म्हणून वाचतो आणि निर्णय दुर्लक्षित करतो. Hook 0 exit code ने पूर्ण झाल्यामुळे transcript मध्ये error दिसत नाही. बहुतेक events वर तो text फक्त debug log मध्ये जातो. मात्र UserPromptSubmit, UserPromptExpansion, SessionStart आणि PostModelSwitch वर तो banner सहित model च्या context मध्ये जोडला जातो. तुमच्या profile मधील कोणतेही echo interactive shells मध्येच चालेल, अशा प्रकारे wrap करा.
  • तरीही समस्या सुटत नसल्यास, claude --debug-file /tmp/claude.log वापरून session सुरू करा आणि दुसऱ्या terminal मध्ये tail -f /tmp/claude.log चालवा. Debug log मध्ये कोणते hooks match झाले, प्रत्येकाने कोणता exit code परत केला आणि त्यांनी stdout व stderr मध्ये काय लिहिले, याची नोंद होते.

FAQ

Claude Code hook आणि CLAUDE.md instruction यांच्यात काय फरक आहे?

CLAUDE.md instruction हा model च्या context मधील मजकूर असतो. त्यामुळे तो conversation आणि सध्याच्या request सोबत लक्ष वेधून घेण्यासाठी स्पर्धा करतो आणि model त्यांचा विचार करून त्याचे वजन ठरवू शकतो. Hook हा Claude Code ने त्याच्या lifecycle मधील निश्चित टप्प्यावर चालवलेला shell command असतो. त्यामुळे model ने काहीही ठरवले तरी संबंधित event प्रत्येक वेळी घडल्यावर तो execute होतो. Preference साठी instruction वापरा. नेहमी घडणे आवश्यक असलेल्या step साठी किंवा कधीही घडू नये अशा action साठी hook वापरा.

Claude Code ला विशिष्ट shell command चालवण्यापासून कसे थांबवायचे?

PreToolUse hook नोंदवा आणि Bash matcher वापरा. तो command .tool_input.command मधून वाचेल, stderr वर कारण लिहील आणि 2 ने exit होईल. Claude Code तो call रद्द करतो आणि तुमचे कारण model ला दाखवतो. हे permission-mode check पूर्वी घडते. त्यामुळे bypassPermissions mode मध्येही deny लागू राहतो. Command string वर pattern matching करणे हे security boundary नसून guardrail आहे. कारण तोच command pattern मध्ये न सापडणाऱ्या पद्धतीने लिहिता येतो. त्यामुळे permission rules आणि unprivileged account यांचा आधार घ्या.

माझा hook वैध JSON print करतो, पण काहीही का घडत नाही?

JSON च्या आधी काही मजकूर print होतो का हे तपासण्यासाठी तुमचे shell profile तपासा. macOS आणि Linux वर args field नसलेला hook sh -c मार्फत चालतो. तुमचे profile अजूनही source होत असलेल्या setups मध्ये, जसे BASH_ENV कडे ~/.bashrc निर्देशित करत असेल, banner print करणारे profile तुमच्या JSON च्या आधी stdout वर तो मजकूर लिहिते. त्यामुळे output ची सुरुवात { ने होत नाही. Claude Code संपूर्ण output plain text म्हणून हाताळतो आणि decision दुर्लक्षित करतो. Hook 0 ने exit झाल्यामुळे transcript मध्ये error देखील दिसत नाही. तुमच्या profile मधील कोणतेही echo interactive-shell test ने संरक्षित करा. त्यानंतर claude --debug-file /tmp/claude.log मधून debug log वाचून दुरुस्तीची खात्री करा.

Shared server वर Claude Code hooks चालवणे सुरक्षित आहे का?

Hooks Claude Code सुरू करणाऱ्या user म्हणून चालतात आणि त्या user च्या file permissions वापरतात. त्यामुळे त्या account ला जे काही करता येते ते hook करू शकतो. धोका कमी करण्यासाठी दोन सवयी पुरेशा ठरतात: agent स्वतंत्र unprivileged account म्हणून, मर्यादित sudo policy सह चालवा; तसेच repository चा workspace trust dialog स्वीकारण्यापूर्वी किंवा त्यात claude -p चालवण्यापूर्वी कोणत्याही repository मधील hooks block वाचा. कारण project hooks .claude/settings.json मध्ये असतात आणि -p mode मध्ये तो dialog कधीही दाखवला जात नाही. Hooks अक्षम करण्यासाठी settings file मध्ये "disableAllHooks": true सेट करा. मात्र managed hooks साठी हे setting managed level वर आवश्यक असते. User setting true असल्यास project setting false ते override करू शकते.

हा लेख उपयुक्त होता का?