SSD Nodes Learn Hosting plans →

Claude Code hooks ఎలా పనిచేస్తాయి: పూర్తి వివరణ

Claude Code hooks అంటే ఏమిటి, అవి ఎలా పనిచేస్తాయి మరియు ఎప్పుడు అమలు అవుతాయో తెలుసుకోండి. Exit code 2 వల్ల టూల్ కాల్ ఎందుకు ఆగిపోతుందో మరియు వీటిలోని భద్రతా అంశాలను ఇక్కడ చూడండి.

Claude Code hook అంటే ఏమిటి

Claude Code hooks అంటే Claude Code తన lifecycle లో నిర్దిష్ట దశల్లో స్వయంగా అమలు చేసే shell commands. Hook మరియు rules file మధ్య ఉన్న ప్రధాన తేడా ఇదే. CLAUDE.md లోని instruction ఒక సూచన మాత్రమే. Model తన context లోని ఇతర సమాచారంతో దాన్ని సరిపోల్చి పరిగణిస్తుంది. Hook code కాబట్టి model అంగీకరించినా, అంగీకరించకపోయినా అది అమలవుతుంది. 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) కు రాసినది reason గా model కు తిరిగి అందుతుంది. అయితే hook blocking decision కలిగిన JSON ను కూడా ముద్రిస్తే, దానిలోని reason కు ప్రాధాన్యం ఉంటుంది.

ఇక్కడి event names మరియు field names Claude Code hooks reference నుంచి తీసుకున్నవి. ఈ reference ను November 12, 2026 న పరిశీలించారు. ఈ interface వేగంగా మారుతోంది. అందువల్ల ఈ వ్యాసంతో సహా ఏదైనా blog post నుంచి JSON ను copy చేసే ముందు, మీ version కు సంబంధించిన reference ను పరిశీలించండి. మీ version ను claude --version తో print చేయండి.

Hook configuration ఎక్కడ ఉంటుంది

Hook అనేది settings file లోని JSON block. ఆ block ను ఆరు ప్రదేశాల్లో ఉంచవచ్చు. Hook పరిధి, అది ఉన్న file పరిధిపైనే ఆధారపడి ఉంటుంది.

  • ~/.claude/settings.json: మీ machine లోని ప్రతి project కు వర్తిస్తుంది. ఇతరుల machine లకు కాదు.
  • .claude/settings.json: ఒక project కు మాత్రమే వర్తిస్తుంది. ఇది repository లో commit అవుతుంది. అందువల్ల repository ను clone చేసే ప్రతి ఒక్కరికీ ఈ hook లభిస్తుంది.
  • .claude/settings.local.json: ఒక project కు మాత్రమే వర్తిస్తుంది. ఇది మీ machine లో మాత్రమే ఉంటుంది.
  • Managed policy settings: సంస్థ మొత్తం కోసం వర్తిస్తాయి. Administrator వీటిని సెట్ చేస్తారు.
  • Plugin లోని hooks/hooks.json: ఆ plugin enabled గా ఉన్నంతకాలం అమల్లో ఉంటాయి.
  • Skill లేదా subagent frontmatter. Skill ను invoke చేసిన తర్వాత, ఆ session మిగిలిన కాలం skill hooks అమల్లో ఉంటాయి. Subagent hooks ఆ subagent నడుస్తున్నంతకాలం అమల్లో ఉంటాయి.

ఈ files లోని hook entries ఒకదానిని మరొకటి override చేయకుండా merge అవుతాయి. Project settings file తన hooks ను user settings లోని hooks కు జోడిస్తుంది; వాటిని భర్తీ చేయదు. అందువల్ల ఒక event కు అనేక files నుంచి వచ్చిన అనేక hooks ఉండవచ్చు. "disableAllHooks": true ను సెట్ చేస్తే hooks నిలిపివేయబడతాయి. అయితే ఒక మినహాయింపు ఉంది: managed policy settings నుంచి వచ్చిన hooks, ఆ setting ను managed settings లో కూడా వర్తింపజేసే వరకు అమల్లోనే ఉంటాయి.

ఒక session లో ప్రస్తుతం registered అయిన ప్రతి hook ను event వారీగా జాబితా చేయడానికి /hooks ను run చేయండి. ప్రతి hook కు సంబంధించిన source file మరియు matcher కూడా ఈ జాబితాలో కనిపిస్తాయి. ఈ menu read-only. అందువల్ల hook ను మార్చాలంటే settings file ను edit చేయాలి. సాధారణంగా file watcher ఈ మార్పును restart లేకుండానే గుర్తిస్తుంది.

ఏ Claude Code హుక్ ఈవెంట్‌లు అందుబాటులో ఉన్నాయి

హుక్స్ రిఫరెన్స్‌లో SessionStart నుండి SessionEnd వరకు ముప్పై మూడు ఈవెంట్‌లు ఉన్నాయి. ఇవి కాంపాక్షన్ (compaction), సబ్-ఏజెంట్లు, వర్క్‌ట్రీలు మరియు కాన్ఫిగరేషన్ ఫైళ్లకు సంబంధించినవి. సర్వర్ పనుల కోసం వీటిలో కొన్నింటిని మాత్రమే ఉపయోగిస్తాము.

  • PreToolUse: ఒక టూల్ కాల్ అమలు కావడానికి ముందు, EndConversation మినహా. ఇది మాత్రమే ప్రాసెస్‌ను నిలిపివేయగలదు (block).
  • PostToolUse: ఒక టూల్ కాల్ విజయవంతమైన తర్వాత, EndConversation మినహా. PostToolUseFailure విఫలమైనప్పుడు ట్రిగ్గర్ అవుతుంది. కాబట్టి, ప్రతి ఫలితాన్ని పర్యవేక్షించాల్సిన హుక్ రెండింటినీ ఉపయోగించాలి.
  • PermissionRequest: టూల్ కాల్‌కు అనుమతి నిర్ణయం అవసరమైనప్పుడు, అంటే అప్రూవల్ ప్రాంప్ట్ కనిపించే సమయం.
  • UserPromptSubmit: మీరు ప్రాంప్ట్‌ను సబ్మిట్ చేసినప్పుడు, Claude దానిని ప్రాసెస్ చేయడానికి ముందు. విజయవంతమైన హుక్ నుండి వచ్చే ప్లెయిన్-టెక్స్ట్ stdout మోడల్ కాంటెక్స్ట్‌కు జోడించబడుతుంది.
  • SessionStart మరియు SessionEnd: సెషన్ ప్రారంభంలో మరియు ముగింపులో. SessionStart కాంపాక్షన్ తర్వాత కూడా ట్రిగ్గర్ అవుతుంది, దీనికి compact మ్యాచర్ విలువను ఉపయోగిస్తారు.
  • Stop: Claude స్పందించడం పూర్తి చేసినప్పుడు. ఇది ప్రతి టర్న్‌కు ఒకసారి జరుగుతుంది, పూర్తి చేసిన పనికి ఒకసారి కాదు.

మ్యాచర్‌లకు మద్దతు ఇచ్చే ఈవెంట్‌లలో, ఒక గ్రూప్ matcherని కలిగి ఉండవచ్చు, ఇది ఏ సందర్భాల్లో హుక్ రన్ అవ్వాలో నిర్ణయిస్తుంది. టూల్ ఈవెంట్‌లలో ఇది టూల్ పేరు ద్వారా ఫిల్టర్ చేస్తుంది, కాబట్టి "Edit|Write" కేవలం ఫైల్ ఎడిట్‌లపై మాత్రమే ట్రిగ్గర్ అవుతుంది. మ్యాచర్‌లు కేస్-సెన్సిటివ్. ఖాళీ మ్యాచర్ ప్రతి సందర్భంలోనూ ట్రిగ్గర్ అవుతుంది. MCP (model context protocol) సర్వర్ నుండి వచ్చే టూల్స్ mcp__<server>__<tool> అని పిలువబడతాయి, కాబట్టి "mcp__github__.*" మ్యాచర్ ఒక సర్వర్ టూల్స్‌ను మాత్రమే పట్టుకుంటుంది, మిగిలిన వాటిని వదిలేస్తుంది.

Stop హుక్స్‌ను రాసే ముందు తెలుసుకోవలసిన ఒక ముఖ్యమైన విషయం ఉంది. Stop హుక్ బ్లాక్ అయినప్పుడు, అది మోడల్‌ను తిరిగి పనికి పంపుతుంది. డిఫాల్ట్‌గా, వరుసగా ఎనిమిది సార్లు కంటిన్యూయేషన్ జరిగిన తర్వాత Claude Code తదుపరి బ్లాక్‌ను ఓవర్‌రైడ్ చేస్తుంది. Claude ఒక టూల్‌ను కాల్ చేసిన ప్రతిసారీ ఈ కౌంట్ రీసెట్ అవుతుంది. హుక్ ఇన్‌పుట్ నుండి stop_hook_active ఫీల్డ్‌ను చదవండి మరియు అది ట్రూ (true) అయినప్పుడు 0 తో ఎగ్జిట్ అవ్వండి, లేకపోతే మీ హుక్ 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 ఉంటాయి; ప్రతి event లో permission_mode పంపబడదు. Tool events లో tool_name, tool_input మరియు tool_use_id కూడా ఉంటాయి. ఇతర events కు వాటి స్వంత fields ఉంటాయి: UserPromptSubmit లో prompt text ఉంటుంది, అలాగే SessionStart లో startup, resume, clear, compact లేదా fork యొక్క source ఉంటుంది.

Shell script లో దీన్ని చదవడానికి సాధారణంగా jq ఉపయోగిస్తారు. Minimal server image లో ఇది ఉండదు. Ubuntu మరియు Debian పై ముందుగా sudo apt install -y jq తో దీన్ని install చేయండి.

టూల్ కాల్ కొనసాగుతున్నప్పుడు exit status ప్రభావం

మూడు ఫలితాలు ఉంటాయి.

  • Exit 0 అంటే విజయవంతమైంది అని అర్థం. చెల్లుబాటు అయ్యే JSON decision 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 నిలిపివేయబడుతుంది. వీటిలో PreToolUse కూడా ఉంది. JSON output లో blocking decision లేకపోతే, stderr లోని విషయం block తో చూపించే message అవుతుంది. JSON output లో blocking decision ఉంటే, దాని reason కు ప్రాధాన్యం ఉంటుంది. ఆ message ను ఎవరు చదువుతారో event పై ఆధారపడి ఉంటుంది. PreToolUse మరియు Stop విషయంలో model దాన్ని reason గా చూస్తుంది. UserPromptSubmit మరియు PreModelSwitch విషయంలో అది మీకు చూపించబడుతుంది. Model context కు అది జోడించబడదు. block చేయలేని PostToolUse మరియు PostToolUseFailure విషయంలో block ను పక్కన పెడతారు. అయితే stderr feedback గా model కు చేరుతుంది. block చేయలేని మిగతా చాలా events లో stderr మీకు మాత్రమే చూపించబడుతుంది లేదా విస్మరించబడుతుంది. Stop, SubagentStop, TaskCompleted మరియు plugin యొక్క UserPromptSubmit hook విషయంలో, stdout ఖాళీగా ఉండి stderr లో missing-file error ఉన్నప్పుడు exit 2 ను block చేయని error గా పరిగణిస్తారు.
  • ఇతర ఏ exit code అయినా, plain-text లేదా ఖాళీ stdout తో వస్తే, సాధారణంగా అది block చేయని error అవుతుంది. Transcript లో Failed with non-blocking status code: text తర్వాత stderr లోని మొదటి line తో కూడిన hook error notice కనిపిస్తుంది. PreToolUse వంటి events లో చెల్లుబాటు అయ్యే JSON ద్వారా outcome ను ఇంకా నిర్ణయించవచ్చు. అయితే hook విఫలమైతే action block అయ్యే సందర్భంలో ఇది వర్తించదు. WorktreeCreate ఏదైనా nonzero exit పై విఫలమవుతుంది. Directory ఆ తర్వాత కూడా ఉంటే, nonzero exit పై WorktreeRemove విఫలమవుతుంది.

Block చేయడం లేదా ఎలాంటి చర్య తీసుకోకుండా ఉండడం కాకుండా మరేదైనా చేయాలంటే exit 0 తో JSON object ను stdout కు పంపండి. 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 ను cancel చేసి reason ను model కు పంపుతుంది. "ask" confirmation కోరుతుంది. ప్రతి hook కు ఒకే style ఎంచుకోండి. stdout లో JSON decision తో పాటు exit 2 ఉపయోగించినా block కొనసాగుతుంది. JSON లో "allow" ఉన్నా ఇదే జరుగుతుంది.

ఒకే event కు అనేక hooks సరిపోతే అవి parallel గా run అవుతాయి. Prompt hooks మరియు agent hooks ఒకేసారి గరిష్ఠంగా పన్నెండు వరకు run అవుతాయి. ఒక hook నుంచి వచ్చే deny దాని sibling hooks ను ఆపదు. అందువల్ల guardrail hook అదే call ను deny చేసినా logging hook తన line ను రాస్తుంది. PreToolUse విషయంలో Claude Code సమాధానాలను merge చేసి, అత్యంత కఠినమైనదాన్ని ఉంచుతుంది. క్రమం deny, defer, ask, allow.

ఉదాహరణ 1: విధ్వంసక ఆదేశం అమలు కాకముందే దాన్ని నిరోధించడం

దీన్ని మీ project లో .claude/hooks/block-destructive.sh గా భద్రపరచండి:

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

దానికి executable అనుమతి ఇచ్చి, తరువాత .claude/settings.json లోని PreToolUse పై register చేయండి:

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 ను process చేస్తూ crash అయితే, onFailure unset గా ఉన్నప్పుడు సాధారణంగా అది open గా విఫలమవుతుంది. Git Bash లేని Windows లో, విఫలమయ్యే shell-form PreToolUse లేదా PermissionRequest command hook బదులుగా tool call ను block చేయవచ్చు:

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

stderr పై Blocked by policy: line కనిపించాలి. Exit code 2 ఉండాలి. ls -la వంటి harmless command ను పంపండి. అప్పుడు output ఏదీ కనిపించకూడదు మరియు exit code 0 ఉండాలి. Session లో, నిరాకరించిన call transcript లో మీ message ను కారణంగా చూపిస్తుంది. Model ఆ message ను చదివి తన ప్రవర్తనను మార్చుకుంటుంది.

దీన్ని చేయడం విలువైనదిగా చేసే ఒక లక్షణం ఉంది: PreToolUse hooks ప్రతి permission mode లో permission-mode check కు ముందే అమలవుతాయి. అందువల్ల 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 లోనూ ఉండాలి.

ప్రతి సవరణ తర్వాత format మరియు lint చేయడం

PostToolUse లోని Edit|Write matcher, ఆ రెండు file-editing tools లో ఏదైనా విజయవంతంగా పూర్తైన తర్వాత అమలవుతుంది. దీన్ని .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 file కు indentation తప్పుగా ఉన్న function ను జోడించమని Claude ను అడిగి, ఆ file ను తెరవండి. అది format చేయబడి కనిపిస్తుంది. Hook అమలైనట్లు నిర్ధారించడానికి ఇది సరిపోతుంది, ఎందుకంటే hook విజయవంతంగా పూర్తైతే conversation లో ఏమీ కనిపించదు.

ఇక్కడ exit 2 ఏ మార్పునూ రద్దు చేయదు. Tool ఇప్పటికే అమలైన తర్వాత PostToolUse నడుస్తుంది. అందువల్ల edit ఏ పరిస్థితిలోనైనా disk పై ఉంటుంది. exit 2 వల్ల కలిగే ప్రయోజనం ఏమిటంటే, ruff check output model కు feedback గా చేరుతుంది. అప్పుడు agent తాను ఇప్పుడే ప్రవేశపెట్టిన error ను సరిచేసి, తదుపరి పనికి వెళుతుంది. Commit సమయంలో గుర్తించే lint failure కు, అదే turn లో agent సరిచేసే lint failure కు మధ్య ఇదే తేడా.

ఇక్కడ రెండు matcher పరిమితులు ముఖ్యమైనవి. Shell command ద్వారా మార్చిన files ను Edit|Write చూడదు. Claude తరచుగా Bash ద్వారా files రాస్తుంది. అందువల్ల ఈ లోటు వాస్తవమైనదే. ప్రతి call కు coverage కావాలంటే, Bash ను కూడా match చేసి, మార్చిన files ను git status --porcelain తో script జాబితా చేయాలి. ప్రతి turn కు ఒకసారి coverage కావాలంటే, scan ను బదులుగా Stop hook లో ఉంచండి.

ఉదాహరణ 3: ఆడిట్ కోసం ప్రతి టూల్ కాల్‌ను లాగ్ చేయడం

PostToolUse పై ఉన్న ఖాళీ మ్యాచర్, EndConversation మినహా ప్రతి విజయవంతమైన టూల్ కాల్‌పై పనిచేస్తుంది. రికార్డును హోమ్ డైరెక్టరీలోని ఫైల్‌కు కాకుండా సిస్టమ్ జర్నల్‌కు పంపడం వల్ల అది ఏజెంట్ యొక్క సొంత షెల్ పరిధి నుండి తప్పించుకోలేదు: యాక్సెస్ అనేది ఆ అకౌంట్ యొక్క అనుమతులపై ఆధారపడి ఉంటుంది. వినియోగదారులు తమ సొంత ప్రైవేట్ జర్నల్‌లను చదువుకోగలరు, అలాగే root మరియు systemd-journal, adm లేదా wheel సభ్యులు అన్ని జర్నల్ ఫైళ్లను చదవగలరు:

{
  "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 లైన్ కనిపిస్తుంది, కొత్తవి చివరన ఉంటాయి. ఏమీ కనిపించకపోతే, జర్నల్ యాక్సెస్‌ను మరియు హుక్ రన్ అయ్యిందో లేదో తనిఖీ చేయండి; దిగువన ఉన్న ట్రబుల్షూటింగ్ విభాగం హుక్ గురించి వివరిస్తుంది.

విఫలమైన కాల్‌లను క్యాప్చర్ చేయడానికి PostToolUseFailure కింద అదే బ్లాక్‌ను జోడించండి, ఎందుకంటే PostToolUse కేవలం విజయం సాధించినప్పుడు మాత్రమే పనిచేస్తుంది మరియు సాధారణంగా విఫలమైన కమాండ్లే ముఖ్యమైనవి. మీ హోమ్ డైరెక్టరీలోని ఫైల్‌కు అపెండ్ చేయడానికి బదులుగా logger ని ఉపయోగించడానికి కారణం యాజమాన్యం (ownership): ఒక హుక్ ఏజెంట్ షెల్ ఉన్న అదే యూజర్‌గా రన్ అవుతుంది, కాబట్టి ఆ యూజర్ దేనినైతే అపెండ్ చేయగలరో, దానిని డిలీట్ (truncate) కూడా చేయగలరు. జర్నల్ systemd-journald ద్వారా వ్రాయబడుతుంది; దానిని తొలగింపు నుండి రక్షించడం అనేది ఇప్పటికీ ఏజెంట్ అకౌంట్ యొక్క ప్రివిలేజ్‌లపైనే ఆధారపడి ఉంటుంది.

హుక్ ఎంత సమయం రన్ అవ్వవచ్చు

చార్ట్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
  }
]

ఒక కమాండ్ హుక్ డిఫాల్ట్‌గా 600 సెకన్ల సమయాన్ని పొందుతుంది, అంటే పది నిమిషాలు. కొన్ని ఈవెంట్‌లు ఈ సమయాన్ని గణనీయంగా తగ్గిస్తాయి. SessionEnd హుక్‌లు అన్నీ కలిసి 1.5 సెకన్ల బడ్జెట్‌ను పంచుకుంటాయి, కాబట్టి సెషన్ ముగింపులో చేసే క్లీనప్ వేగంగా జరగాలి. అయితే, మీ సెట్టింగ్స్ ఫైల్‌లలోని హుక్‌కు ఎక్కువ timeout సెట్ చేయడం ద్వారా, ఆ భాగస్వామ్య బడ్జెట్‌ను 60 సెకన్ల వరకు పెంచుకోవచ్చు.

సమయం ముగిసిన (timeout) సింక్రోనస్ కమాండ్, HTTP లేదా MCP టూల్ హుక్ రద్దు చేయబడుతుంది మరియు సాధారణంగా ఎటువంటి నిర్ణయాన్ని ఇవ్వదు; PreModelSwitch విషయంలో, టైమ్‌అవుట్ స్విచ్‌ను నిరోధిస్తుంది. PreToolUse గార్డ్‌రైల్ కోసం, టైమ్‌అవుట్ సాధారణంగా టూల్ కాల్‌ను సాధారణ అనుమతి ప్రవాహంలోకి కొనసాగనిస్తుంది. అయితే, onFailure సెట్ చేయనప్పుడు పైన పేర్కొన్న Windows మినహాయింపు వర్తిస్తుంది. ఈ కారణం చేత గార్డ్‌రైల్ స్క్రిప్ట్‌లను చిన్నవిగా ఉంచండి. 2.1.295 రిలీజ్ నుండి, మీరు command లేదా http హుక్‌పై "onFailure": "block" తో ఆ డిఫాల్ట్‌ను మార్చవచ్చు. ఇది టైమ్‌అవుట్, క్రాష్ లేదా ఊహించని ఎగ్జిట్ కోడ్‌ను బ్లాక్‌గా మారుస్తుంది. అయితే, ఇది Stop, SubagentStop, TaskCompleted, TeammateIdle లేదా బ్యాక్‌గ్రౌండ్ కమాండ్ హుక్స్‌పై ఎటువంటి ప్రభావం చూపదు. లాగ్‌లను ఎక్కడికైనా పంపడం వంటి నెమ్మదిగా జరిగే పనుల కోసం, ఎవరూ వేచి ఉండాల్సిన అవసరం లేనప్పుడు, "async": true సెట్ చేయండి. అప్పుడు ఆ హుక్ టూల్ కాల్‌ను ఆపకుండా బ్యాక్‌గ్రౌండ్‌లో రన్ అవుతుంది.

Hooks, rules files, skills మరియు MCP servers

ఏజెంట్ చేసే పనిని మార్చే నాలుగు అంశాలు ఒకదానితో ఒకటి గందరగోళానికి గురిచేస్తాయి. వీటిలో ఒకటి మాత్రమే సూచనగా ఉండటం ఆపివేస్తుంది.

ఒక rules file (CLAUDE.md, లేదా .claude/rules/ కింద ఉన్న ఫైల్) అనేది మోడల్ యొక్క context లోకి లోడ్ చేయబడిన టెక్స్ట్. ఇది ప్రవర్తనను రూపొందిస్తుంది కానీ దేనినీ బలవంతంగా అమలు చేయదు. సుదీర్ఘ సంభాషణ, పెద్ద diff మరియు కొత్త యూజర్ అభ్యర్థనల మధ్య, ఇందులో ఉన్న ఒక లైన్ ప్రభావం కోల్పోవచ్చు. ఏజెంట్లు మీరు రాసిన సూచనలను విస్మరించడం వెనుక ఉన్న సాధారణ కారణం ఇదే.

ఒక skill అనేది మోడల్ తనకు సంబంధితమని భావించినప్పుడు లోడ్ చేసే సూచనలు మరియు స్క్రిప్ట్‌ల ఫోల్డర్. ఆ నిర్ణయం తీసుకోవడమే skill యొక్క ముఖ్య ఉద్దేశ్యం, అదే దాని పరిమితి కూడా: మోడల్ ఇప్పటికీ నిర్ణయం తీసుకుంటుంది. Ponytail, ఇది ఏజెంట్‌ను పని చేసే అతి చిన్న మార్పు వైపు నెడుతుంది వంటి skill లో మీరు రెండు వైపులా చూడవచ్చు, ఎందుకంటే ఇది ఏ hook చేయలేని విధంగా మొత్తం పనిని ఎలా చేయాలో రూపొందిస్తుంది, మరియు మోడల్ దానిని లోడ్ చేయాలని ఎంచుకున్నప్పుడు మాత్రమే ఇది పనిచేస్తుంది.

ఒక MCP (model context protocol) server మోడల్‌కు కాల్ చేయడానికి కొత్త సాధనాలను అందిస్తుంది. ఇది ఏజెంట్ చేరుకోగల పరిధిని విస్తరిస్తుంది. ఇది ఏజెంట్‌ను దేనినైనా చేయమని బలవంతం చేయదు, మరియు ఇది మీరు నిర్వహించాల్సిన ఒక ప్రత్యేక ప్రక్రియ, ఇది ఒక విడిగా చేయాల్సిన పని: VPS పై MCP servers ను రన్ చేయడం చూడండి.

ఈ నాలుగింటిలో మోడల్ ఎంపికతో సంబంధం లేకుండా రన్ అయ్యేది hook మాత్రమే. ఒక ప్రాధాన్యత కోసం rules file ను, మరియు మోడల్ అనుసరించాల్సిన విధానం కోసం skill ను ఉపయోగించండి. ప్రతిసారీ జరగాల్సిన దశ కోసం లేదా ఎప్పటికీ జరగకూడని పని కోసం hook ను ఉపయోగించండి. skill ఎప్పుడు rules file కంటే మెరుగ్గా పనిచేస్తుందనే దానితో సహా లోతైన పోలిక skills, MCP మరియు rules files మధ్య పోలిక లో ఉంది.

plugin అనేది ఐదవ విధానం కాదు, ఇది కేవలం ప్యాకేజింగ్ మాత్రమే. ఇది hooks మరియు skills ను ఒకే install చేయదగిన యూనిట్‌గా కలుపుతుంది, దీని ద్వారా ఒక బృందం ప్రతి మెషీన్‌కు ఒకే రకమైన guardrail ను పంపిస్తుంది: Claude Code plugins ఎలా పనిచేస్తాయి చూడండి.

భాగస్వామ్య VPS పై భద్రతా నిర్ణయం

Hook అనేది agent trigger చేసే code. అది Claude Code ను ప్రారంభించిన user గానే అమలవుతుంది. ఆ user కు ఉన్న file permissions మరియు environment ను అది పొందుతుంది. Laptop పై ఇది workflow కు సంబంధించిన విషయం. Agent unattended గా నడిచే 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 block ను చదవండి. సాధారణంగా unattended agent నడిచే విధంగా ఉపయోగించే claude -p లేదా SDK session ఎప్పుడూ ఆ dialog ను చూపదు. అది folder ను trusted గా పరిగణిస్తుంది. కాబట్టి repository hooks అడగకుండానే అమలవుతాయి. దానిపై scripts రాయడానికి ముందు దాని .claude/ files ను పరిశీలించండి. లేదా --settings '{"disableAllHooks": true}' తో అమలు చేయండి.

Hook కు పూర్తి tool input కనిపిస్తుంది. tool_input ను log చేసే audit hook ప్రతి command యొక్క ప్రతి argument ను log లో రాస్తుంది. అందులో command line పై ఉన్న ఏదైనా token కూడా ఉండవచ్చు. కాబట్టి ఆ log కు secret కు ఇచ్చే రక్షణతో సమానమైన రక్షణ అవసరం. ఇది AI agent కు secrets అందకుండా ఉంచడం అనే విస్తృత సమస్యలో భాగం.

Hook model context లోకి రాయగలదు. విజయవంతమైన SessionStart లేదా UserPromptSubmit hook నుంచి వచ్చే plain-text stdout conversation కు జోడించబడుతుంది. బయట నుంచి, issue tracker నుంచి లేదా log file నుంచి text ను pipe చేసే hook, మీరు స్వయంగా టైప్ చేసినట్టుగా untrusted text ను model కు అందిస్తుంది. అదే VPS పై నడుస్తున్న మరో Claude Code session నుంచి note ను forward చేసే hook కూడా అదే పని చేస్తుంది. Issue tracker output కంటే ఒక agent output పై మీకు ఎక్కువ నమ్మకం ఉండదు. ఆ stdout ను output గా కాకుండా input గా పరిగణించండి.

వాస్తవ నియంత్రణ privilege పైనే ఉంటుంది. Agent ను dedicated unprivileged user గా నడపండి. దానికి అవసరమైన sudo rules మాత్రమే ఇవ్వండి. PreToolUse deny ఉపయోగకరంగా ఉంటుంది. అయితే ఇది రూపకల్పన ప్రకారం best effort మాత్రమే. if filter విషయంలో కూడా reference ఇదే చెబుతుంది. గట్టి deny అవసరమైనప్పుడు permission system ను ఉపయోగించాలని అది సూచిస్తుంది. ఒత్తిడి వచ్చినప్పుడు కూడా అమలులో ఉండే భాగాలు permission rules మరియు process నడిచే account.

ప్రతి permission mode లోనూ ఒక నియమం వర్తిస్తుంది. PreToolUse hooks ప్రతి permission mode లో permission-mode check కు ముందు అమలవుతాయి. అందువల్ల deny ను తిరిగి ఇచ్చే hook, bypassPermissions లో కూడా tool ను block చేస్తుంది. Hooks, permission rules అనుమతించే చర్యలను మరింత పరిమితం చేయగలవు. వాటిని సడలించలేవు. Mod దీనికి మినహాయింపు. Managed settings లేని machine పై, managed-mcp.json file లేని session లో, Team లేదా Enterprise plan కు /login ద్వారా sign in కాని స్థితిలో, tool.check ను handle చేసే 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 లేదా long-lived CLAUDE_CODE_OAUTH_TOKEN పై నడిచే session — అనేక servers లో ఇదే విధంగా నడుస్తుంది — login నిల్వ ఉన్నప్పటికీ signed in కానిదిగా పరిగణించబడుతుంది. Server పై mod install చేసే ముందు Claude Code mods ఏ మార్పులు చేయగలవో పరిశీలించండి.

నా hook ఎందుకు అమలు కావడం లేదు?

ఈ క్రమంలో పరిశీలించండి. ప్రతి దశలో మీరు వాస్తవంగా కనిపించే లక్షణం వివరించబడుతుంది.

  • /hooks అమలు చేసి, మీరు ఆశించిన event కింద hook కనిపిస్తుందో చూడండి. Menuలో hook కనిపించకపోవడం సాధారణంగా settings fileలో JSON syntax error ఉందని సూచిస్తుంది. Trailing commas మరియు comments అనుమతించబడవు. లేదా ఆ file పైన పేర్కొన్న ఆరు locationsలో ఏదీ లేకపోవచ్చు.
  • Matcherను tool nameతో అచ్చుగా పోల్చండి. Matchers case sensitiveగా ఉంటాయి. అందువల్ల "bash", Bash toolతో ఎప్పుడూ match కాదు.
  • పై example 1లో చూపినట్లుగా sample inputతో scriptను చేతితో అమలు చేయండి. మీరు ఆశించని exit code వస్తే, మీ scriptలో bug ఉంది. దాని stdoutను కూడా పరిశీలించండి. చెల్లుబాటు అయ్యే JSON అయినప్పటికీ PreToolUse వంటి eventsపై ఒక decision ఇవ్వవచ్చు.
  • jq: command not found అనే notice కనిపిస్తే, ఆ machineలో jq లేదు. మీ స్వంత script కోసం command not found కనిపిస్తే, path resolve కాలేదని అర్థం. కాబట్టి ${CLAUDE_PROJECT_DIR} లేదా absolute path ఉపయోగించండి. Script అసలు అమలు కాకపోతే, అది executable కాకపోవచ్చు.
  • Hook valid JSONను print చేసినా ఏమీ జరగడం లేదు. macOS మరియు Linuxలో shell-form hook non-interactive shellలో sh -c ద్వారా అమలు అవుతుంది. అయితే కొన్ని setups మీ profileను source చేస్తాయి. ఉదాహరణకు BASH_ENV, ~/.bashrc ను సూచిస్తే ఇలా జరగవచ్చు. ఆ profile bannerను print చేస్తే, ఆ banner మీ JSONకు ముందుగా జతచేయబడుతుంది. అందువల్ల stdout ఇక {తో ప్రారంభం కాదు. Claude Code మొత్తం outputను plain textగా చదివి decisionను విస్మరిస్తుంది. Hook exit 0తో ముగిసినందున transcriptలో error కనిపించదు. చాలా eventsలో ఆ text debug logకు మాత్రమే వెళ్తుంది. కానీ UserPromptSubmit, UserPromptExpansion, SessionStart మరియు PostModelSwitch eventsలో bannerతో సహా అది model contextకు జతచేయబడుతుంది. మీ profileలోని ఏదైనా echo ను interactive shellsలో మాత్రమే అమలు అయ్యేలా wrap చేయండి.
  • ఇంకా సమస్య పరిష్కారం కాకపోతే, sessionను claude --debug-file /tmp/claude.log తో ప్రారంభించి, రెండవ terminalలో tail -f /tmp/claude.log అమలు చేయండి. Debug logలో ఏ hooks match అయ్యాయి, ప్రతి hook ఏ exit codeతో ముగిసింది, అలాగే అవి stdout మరియు stderrకు ఏమి రాశాయి అన్నది నమోదవుతుంది.

FAQ

Claude Code hook మరియు CLAUDE.md instruction మధ్య తేడా ఏమిటి?

CLAUDE.md instruction అనేది model context లోని text. అందువల్ల అది conversation మరియు ప్రస్తుత request తో attention కోసం పోటీ పడుతుంది. Model వాటితో పోల్చి దానికి ఎంత ప్రాధాన్యం ఇవ్వాలో నిర్ణయించవచ్చు. Hook అనేది Claude Code తన lifecycle లోని నిర్దిష్ట దశలో అమలు చేసే shell command. అందువల్ల model ఏ నిర్ణయం తీసుకున్నా, దానికి సంబంధించిన event జరిగిన ప్రతిసారీ అది అమలవుతుంది. Preference కోసం instruction ఉపయోగించండి. ఎల్లప్పుడూ జరగాల్సిన step లేదా ఎప్పుడూ జరగకూడని action కోసం hook ఉపయోగించండి.

Claude Code ఒక నిర్దిష్ట shell command ను అమలు చేయకుండా ఎలా ఆపాలి?

.tool_input.command నుంచి command ను చదివి, stderr కు కారణాన్ని రాసి, 2 తో exit అయ్యే PreToolUse hook ను register చేయండి. Bash matcher ను ఉపయోగించండి. Claude Code ఆ call ను cancel చేసి, మీ కారణాన్ని model కు చూపిస్తుంది. ఇది permission-mode check కు ముందే జరుగుతుంది. అందువల్ల bypassPermissions mode లో కూడా deny అమలులో ఉంటుంది. Command string పై pattern matching ఒక guardrail మాత్రమే, security boundary కాదు. అదే command ను pattern గుర్తించని వేరే రూపంలో రాయవచ్చు. కాబట్టి దీనికి permission rules మరియు unprivileged account ను కూడా జత చేయండి.

నా hook చెల్లుబాటు అయ్యే JSON ను print చేస్తోంది, కానీ ఏమీ జరగడం లేదు. ఎందుకు?

JSON కు ముందు text print అవుతుందేమో తెలుసుకోవడానికి మీ shell profile ను పరిశీలించండి. macOS మరియు Linux లో args field లేని hook, sh -c ద్వారా అమలవుతుంది. BASH_ENV, ~/.bashrc ను point చేసే setup వంటి సందర్భాల్లో మీ profile source అయితే, banner ను print చేసే profile మీ JSON కు ముందు ఆ banner ను stdout కు పంపుతుంది. Output ఇక { తో ప్రారంభం కాకపోవడంతో Claude Code మొత్తం output ను plain text గా పరిగణించి decision ను పట్టించుకోదు. Hook 0 తో exit అయినందున transcript లో error కూడా కనిపించదు. మీ profile లోని ఏదైనా echo ను interactive-shell test తో guard చేయండి. తరువాత claude --debug-file /tmp/claude.log నుంచి debug log చదివి fix నిర్ధారించండి.

Shared server పై Claude Code hooks అమలు చేయడం సురక్షితమేనా?

Hooks ను Claude Code ప్రారంభించిన user గానే అమలు చేస్తాయి. ఆ user కు ఉన్న file permissions తోనే అవి పనిచేస్తాయి. అందువల్ల ఆ account చేయగలిగిన పనిని hook కూడా చేయగలదు. ప్రమాదంలో ఎక్కువ భాగాన్ని తగ్గించడానికి ఈ రెండు అలవాట్లు పాటించండి: agent ను పరిమిత sudo policy కలిగిన dedicated unprivileged account గా అమలు చేయండి. Workspace trust dialog ను accept చేయడానికి లేదా దానిలో claude -p అమలు చేయడానికి ముందు ఏ repository లోనైనా ఉన్న hooks block ను చదవండి. ఎందుకంటే project hooks .claude/settings.json లో ఉంటాయి. -p mode ఆ dialog ను ఎప్పుడూ చూపించదు. Hooks ను disable చేయడానికి మీ settings file లో "disableAllHooks": true ను సెట్ చేయండి. అయితే managed hooks కు managed level లో ఈ setting అవసరమైతే వాటికి ఇది మినహాయింపు. User setting true గా ఉన్నప్పుడు project setting false దాన్ని override చేయవచ్చు.

ఈ వ్యాసం ఉపయోగకరంగా ఉందా?