Claude Code Hooks: Events, Exit Code 2, Security

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 ను register చేస్తారు. ఆ 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 కు తిరిగి అందుతుంది.

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

హుక్ కాన్ఫిగరేషన్ ఎక్కడ ఉంటుంది

హుక్ అనేది settings file లోని JSON block. ఆరు స్థానాల్లో ఒకటి ఉండవచ్చు. హుక్ పరిధి, దాన్ని కలిగి ఉన్న file పరిధిపై ఆధారపడి ఉంటుంది.

• ~/.claude/settings.json: మీ machine లోని ప్రతి project కు వర్తిస్తుంది. ఇతరుల machine లకు కాదు.
• .claude/settings.json: ఒక project కు మాత్రమే వర్తిస్తుంది. ఇది repository లో commit అవుతుంది కాబట్టి, దాన్ని clone చేసే ప్రతి ఒక్కరికీ హుక్ లభిస్తుంది.
• .claude/settings.local.json: ఒక project కు మాత్రమే వర్తిస్తుంది. మీ machine లో మాత్రమే ఉంటుంది.
• Managed policy settings: సంస్థ మొత్తం కోసం administrator సెట్ చేస్తారు.
• Plugin లోని hooks/hooks.json: ఆ plugin enabled గా ఉన్నంతకాలం అమల్లో ఉంటుంది.
• Skill లేదా subagent frontmatter: ఆ component active గా ఉన్నంతకాలం అమల్లో ఉంటుంది.

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

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

Claude Code hook eventలు ఏవి అందుబాటులో ఉన్నాయి

Release 2.1.232 లో SessionStart నుంచి SessionEnd వరకు మొత్తం thirty one eventలు ఉన్నాయి. ఇవి compaction, subagents, worktrees మరియు configuration files వంటి అంశాలను కవర్ చేస్తాయి. Server పనిలో వీటిలో కొన్నింటినే సాధారణంగా ఉపయోగిస్తారు.

• PreToolUse: tool call అమలు కావడానికి ముందు. దీన్ని ఉపయోగించి అమలును ఆపవచ్చు.
• PostToolUse: tool call విజయవంతమైన తర్వాత. అది విఫలమైనప్పుడు PostToolUseFailure అమలవుతుంది. అందువల్ల ప్రతి ఫలితాన్ని గమనించాల్సిన hook కు రెండూ అవసరం.
• PermissionRequest: tool call కు permission నిర్ణయం అవసరమైనప్పుడు. ఈ సమయంలో approval prompt కనిపిస్తుంది.
• UserPromptSubmit: prompt సమర్పించినప్పుడు, Claude దాన్ని process చేయడానికి ముందు. ఈ hook stdout కు రాసే ఏదైనా model context కు జోడించబడుతుంది.
• SessionStart మరియు SessionEnd: session ప్రారంభం మరియు ముగింపులో. Compaction తర్వాత కూడా SessionStart అమలవుతుంది; అప్పుడు matcher విలువ compact ఉంటుంది.
• Stop: Claude స్పందించడం పూర్తిచేసినప్పుడు. ఇది పూర్తయిన ప్రతి task కు కాదు, ప్రతి turn కు ఒకసారి అమలవుతుంది.

ప్రతి group లో hook ఏ సందర్భాల్లో అమలవుతుందో నిర్ణయించే matcher ఉంటుంది. Tool eventలలో ఇది tool name ఆధారంగా filter చేస్తుంది. అందువల్ల "Edit|Write" file edits పై మాత్రమే అమలవుతుంది; ఇతర సందర్భాల్లో కాదు. Matchers case sensitive. ఖాళీ matcher ప్రతి సందర్భంలో అమలవుతుంది. MCP (model context protocol) server నుంచి వచ్చే tools కు mcp__<server>__<tool> పేర్లు ఉంటాయి. కాబట్టి "mcp__github__.*" matcher ఒక server కు చెందిన tools ను మాత్రమే పట్టుకుంటుంది; ఇతర serverల tools ప్రభావితం కావు.

Stop hooks లో hook రాసే ముందు తెలుసుకోవాల్సిన ఒక పరిమితి ఉంది. అమలును ఆపే Stop hook model ను మళ్లీ పనికి పంపుతుంది. వరుసగా eight blocks జరిగిన తర్వాత Claude Code ఆ hook ను override చేస్తుంది. Hook input నుంచి stop_hook_active field చదవండి. దాని విలువ true అయినప్పుడు 0 తో exit చేయండి. లేకపోతే hook ఆ పరిమితిని చేరుకునే వరకు loop అవుతుంది.

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

ప్రతి event లో session_id, cwd, permission_mode, transcript_path మరియు hook_event_name ఉంటాయి. Tool events లో అదనంగా tool_name, tool_input మరియు tool_use_id ఉంటాయి. ఇతర events కు వాటి స్వంత fields ఉంటాయి: UserPromptSubmit లో prompt text ఉంటుంది, మరియు SessionStart లో startup యొక్క source, అంటే resume, clear, compact లేదా fork లో ఒకటి ఉంటుంది.

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

టూల్ call అమలులో ఉన్నప్పుడు exit status ప్రభావం

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

• Exit 0 అంటే మీ hook ఎలాంటి అభ్యంతరం వ్యక్తం చేయలేదని అర్థం. PreToolUse లో ఇది approval కు సమానం కాదు; సాధారణ permission flow ఇంకా కొనసాగుతుంది. UserPromptSubmit మరియు SessionStart లో stdout model context కు జోడించబడుతుంది.
• Exit 2 అంటే block చేయగల events లో action ను నిలిపివేస్తుంది. వాటిలో PreToolUse కూడా ఉంది. stderr లోని విషయం model కు చూపబడే కారణంగా మారుతుంది. PostToolUse వంటి block చేయలేని events లో block ను విస్మరిస్తారు. అయితే stderr feedback గా model కు చేరుతుంది.
• ఇతర ఏ exit code అయినా non-blocking error గా పరిగణించబడుతుంది. Action కొనసాగుతుంది. Failed with non-blocking status code: అనే text తర్వాత stderr లోని మొదటి line ను కలిగి ఉన్న hook error notice transcript లో చూపబడుతుంది.

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

"allow" interactive prompt ను దాటవేస్తుంది, "deny" call ను cancel చేసి కారణాన్ని model కు పంపుతుంది, "ask" prompt ను సాధారణంగా చూపిస్తుంది. ప్రతి hook కు ఒకే style ఎంచుకోండి. stdout లో exit 2 తో పాటు JSON decision కలిపి ఉపయోగిస్తే, ఫలితాన్ని మీరు స్వయంగా పరిశీలించాల్సి ఉంటుంది.

ఒకే event కు అనేక hooks సరిపోతే అవి parallel గా అమలవుతాయి. ప్రతి hook పూర్తి అయ్యే వరకు అమలవుతుంది. ఒక hook నుంచి వచ్చే deny దాని sibling hooks ను ఆపదు. అందువల్ల guardrail hook అదే call ను నిరాకరించినప్పటికీ logging hook తన line ను రాస్తుంది. తరువాత Claude Code సమాధానాలను merge చేసి, deny, defer, ask, allow అనే క్రమంలో అత్యంత restrictive నిర్ణయాన్ని ఉంచుతుంది.

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

దీన్ని మీ project లో .claude/hooks/block-destructive.sh గా save చేయండి:

#!/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 ను చేతితో test చేయండి. ఎందుకంటే స్వంత input ను process చేస్తున్నప్పుడు crash అయ్యే hook, open గా fail అవుతుంది:

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 వంటి హానికరం కాని command ను దానికి ఇవ్వండి. అప్పుడు output ఏదీ కనిపించకూడదు మరియు 0 exit code రావాలి. Session లో నిరాకరించిన call, కారణంగా మీరు ఇచ్చిన message తో transcript లో కనిపిస్తుంది. 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 ఉద్దేశపూర్వకంగా వేరే రూపంలో అదే command రాయగలదు కాబట్టి, ఇది agent తెలివిగా దాటవేయకుండా అడ్డుకునే boundary కాదు. అలాంటి రూపాన్ని మీ grep చూడకపోవచ్చు. కఠినమైన నియమాలను permission system లో మరియు process అమలు చేసే account లో ఉంచాలి.

ప్రతి సవరణ తర్వాత format మరియు lint నిర్వహించే ఉదాహరణ 2

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
          }
        ]
      }
    ]
  }
}

Python ఫైల్‌లో indentation సరిగా లేని function ను జోడించమని Claude ను అడిగి, ఆ ఫైల్‌ను తెరవండి. ఫైల్ formatted గా కనిపిస్తుంది. Hook నడిచిందని నిర్ధారించడానికి ఇదే సరిపోతుంది, ఎందుకంటే hook విజయవంతంగా నడిస్తే conversation లో ఏ output కనిపించదు.

ఇక్కడ exit 2 వల్ల ఏదీ undo కాదు. Tool ఇప్పటికే అమలైన తర్వాత PostToolUse నడుస్తుంది. కాబట్టి edit ఏ పరిస్థితిలోనైనా disk పై ఉంటుంది. exit 2 వల్ల కలిగే ప్రయోజనం ఏమిటంటే ruff check output model కు feedback గా చేరుతుంది. అందువల్ల అది ఇప్పుడే ప్రవేశపెట్టిన 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: audit కోసం ప్రతి tool call ను log చేయడం

PostToolUse పై ఖాళీ matcher ప్రతి tool పై అమలవుతుంది. Record ను home directory లోని file కు కాకుండా system journal కు పంపితే, agent స్వంత shell కు అది అందుబాటులో ఉండదు:

{
  "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 తో దాన్ని తిరిగి చదవండి. ప్రతి tool call కు ఒక్క JSON line చొప్పున కనిపించాలి; చివరిది అత్యంత కొత్త record అయి ఉంటుంది. ఏదీ కనిపించకపోతే hook అమలు కాలేదని అర్థం. దిగువ troubleshooting విభాగంలో దీనికి సంబంధించిన వివరాలు ఉన్నాయి.

విఫలమైన calls ను కూడా capture చేయడానికి PostToolUseFailure కింద ఇదే block ను జోడించండి. ఎందుకంటే PostToolUse విజయవంతమైనప్పుడు మాత్రమే అమలవుతుంది, అయితే విఫలమైన command సాధారణంగా ఎక్కువ సమాచారం ఇస్తుంది. మీ home directory లోని file కు append చేయకుండా logger ఉపయోగించడానికి కారణం ownership. Hook agent యొక్క shell నడుస్తున్న అదే user గా అమలవుతుంది. కాబట్టి ఆ user ఏ file కు append చేయగలిగితే, దాని contents ను truncate కూడా చేయగలడు. Journal ను systemd-journald తన స్వంత account కింద వ్రాస్తుంది.

హుక్ ఎంతసేపు అమలు కావచ్చు

[
  {
    "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 hook on UserPromptSubmit",
    "default_timeout_seconds": 30
  },
  {
    "label": "command hook on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

command hook కు డిఫాల్ట్‌గా 600 సెకన్ల సమయం ఉంటుంది. ఇది పది నిమిషాలకు సమానం. కొన్ని events ఈ సమయాన్ని గణనీయంగా తగ్గిస్తాయి. SessionEnd hooks అన్నీ కలిపి 1.5 సెకన్ల shared budget ను ఉపయోగిస్తాయి. అందువల్ల session ముగింపు cleanup వేగంగా పూర్తవాలి. అయితే hook పై ఎక్కువ సమయాన్ని కేటాయించే timeout ను సెట్ చేస్తే, ఆ shared budget కూడా అదే విలువకు పెరుగుతుంది. గరిష్ఠంగా 60 సెకన్ల వరకు పెంచవచ్చు.

Timeout చేరుకున్న hook రద్దవుతుంది. అది ఎలాంటి నిర్ణయాన్ని ఇవ్వదు. PreToolUse guardrail విషయంలో, అది నిరోధించదు. Tool call సాధారణ permission flow లో కొనసాగుతుంది. అందుకే guardrail scripts ను చిన్నగా ఉంచాలి. ఎవరూ వెంటనే ఫలితం కోసం వేచి ఉండని నెమ్మదైన పనులకు, ఉదాహరణకు log ను మరొకచోటికి పంపడానికి, "async": true ను సెట్ చేయండి. అప్పుడు tool call ఆగకుండా hook background లో అమలవుతుంది.

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

ఇవన్నీ agent చేసే పనిని మార్చుతాయి కాబట్టి, ఈ నాలుగు అంశాలు తరచుగా పరస్పరం కలిసిపోతాయి. వీటిలో సూచనగా ఉండటాన్ని ఆపేది ఒక్కటే.

A rules file (CLAUDE.md లేదా .claude/rules/ కింద ఉన్న file) model context లోకి load అయ్యే text. ఇది ప్రవర్తనను ప్రభావితం చేస్తుంది, కానీ ఏదీ తప్పనిసరి చేయదు. దీర్ఘమైన conversation, పెద్ద diff, కొత్త user request ఉన్నప్పుడు, దానిలోని ఒక్క line ప్రాధాన్యత కోల్పోవచ్చు. మీరు రాసిన instructions ను agents విస్మరించడానికి ఇదే సాధారణ కారణం.

A skill అనేది instructions మరియు scripts ఉన్న folder. model ఆ skill సంబంధితదని నిర్ణయించినప్పుడు దాన్ని load చేస్తుంది. ఆ నిర్ణయమే skill యొక్క ఉద్దేశం, అలాగే దాని పరిమితి కూడా: నిర్ణయం model దే. Ponytail వంటి skill, agent ను పనిచేసే సరైన అతి చిన్న మార్పు వైపు నడిపిస్తుంది. ఇది hook చేయలేని విధంగా మొత్తం task ను ఎలా approach చేయాలో రూపొందిస్తుంది. అయితే model దాన్ని load చేయాలని ఎంచుకున్నప్పుడు మాత్రమే ఇది అమలవుతుంది.

An MCP (model context protocol) server, model కు call చేయగల కొత్త tools ను అందిస్తుంది. దీంతో agent చేరుకోగల పరిధి పెరుగుతుంది. అయితే ఏ tool ను ఉపయోగించాలో అది agent ను బలవంతం చేయదు. ఇది మీరు operate చేయాల్సిన ప్రత్యేక process కూడా; దానికి స్వంత నిర్వహణ అవసరం. VPS పై MCP servers నడపడం చూడండి.

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

Plugin అనేది ఐదవ mechanism కాదు; అది packaging విధానం. ఇది hooks ను skills తో కలిపి ఒక installable unit గా అందిస్తుంది. ఒకే guardrail ను ప్రతి machine కు team పంపిణీ చేసే విధానం ఇదే. Claude Code plugins ఎలా పనిచేస్తాయో చూడండి.

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

Hook అనేది agent trigger చేసే code. ఇది Claude Code ప్రారంభించిన user గానే run అవుతుంది. ఆ user యొక్క environment మరియు file permissions ను ఇది inherit చేసుకుంటుంది. Laptop పై ఇది workflow కు సంబంధించిన ప్రశ్న. Agent unattended గా run అయ్యే VPS పై ఇది నాలుగు ఆచరణాత్మక అంశాలున్న security ప్రశ్న.

Repository లోని hook మీరు రాసిన code కాదు. .claude/settings.json commit అయి ఉంటుంది. అందువల్ల repository ను clone చేసి, దాని లోపల session ప్రారంభిస్తే, repository తో వచ్చిన hooks register కావచ్చు. Claude Code ఆ folder కు సంబంధించిన workspace trust dialog వెనుక project hooks ను ఉంచుతుంది. అంటే trust ను accept చేసే సమయంలోనే వాటిని run చేయాలా వద్దా అని మీరు నిర్ణయిస్తారు. ముందుగా hooks block ను చదవండి.

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

Hook model context లోకి రాయగలదు. SessionStart లేదా UserPromptSubmit hook stdout కు print చేసే ఏదైనా conversation కు జోడించబడుతుంది. బయటి source, issue tracker లేదా log file నుంచి text ను pipe చేసే hook, మీరు స్వయంగా type చేసినట్లుగా untrusted text ను model కు అందిస్తుంది. ఆ stdout ను output గా కాకుండా input గా పరిగణించండి.

Privilege నే అసలు నియంత్రణ. Agent ను ప్రత్యేక unprivileged user గా run చేయండి. దానికి అవసరమైన sudo rules మాత్రమే ఇవ్వండి. PreToolUse deny ఉపయోగకరంగా ఉంటుంది. అయితే ఇది design ప్రకారం best effort మాత్రమే. Reference కూడా if filter గురించి ఇదే చెబుతుంది. Hard deny అవసరమైనప్పుడు permission system ను ఉపయోగించమని సూచిస్తుంది. ఒత్తిడి పరిస్థితుల్లోనూ పనిచేసే అంశాలు permission rules మరియు process run అయ్యే account.

ప్రతి configuration లోనూ ఒక విషయం వర్తిస్తుంది. PreToolUse hooks ప్రతి permission mode లో permission-mode check కు ముందు fire అవుతాయి. అందువల్ల deny return చేసే hook, bypassPermissions లో కూడా tool ను block చేస్తుంది. Permission rules అనుమతించే పరిధిని hooks మరింత కఠినం చేయగలవు. వాటిని సడలించలేవు.

నా 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తో సరిపోలదు.
• పైన ఉన్న example 1లో చూపిన విధంగా sample inputతో scriptను చేతితో అమలు చేయండి. మీరు ఆశించని exit code వస్తే, అది మీ scriptలోని bug. Claude Code దాన్ని decisionగా కాకుండా hook errorగా నివేదిస్తుంది.
• jq: command not found అనే notice కనిపిస్తే, ఆ machineలో jq అందుబాటులో లేదని అర్థం. మీ స్వంత scriptకు command not found కనిపిస్తే, path resolve కాలేదని అర్థం. అందువల్ల ${CLAUDE_PROJECT_DIR} లేదా absolute path ఉపయోగించండి. Script అసలు అమలు కాకపోతే, అది executable కాకపోవచ్చు.
• Hook చెల్లుబాటు అయ్యే JSONను print చేసినా ఏమీ జరగకపోవచ్చు. Shell-form hook sh -c ద్వారా నడుస్తుంది. మీ shell profile bannerను print చేస్తే, ఆ banner మీ JSONకు ముందుగా జతచేయబడుతుంది. Stdout ఇక { తో ప్రారంభం కాదు. అందువల్ల Claude Code మొత్తం outputను plain textగా చదివి decisionను విస్మరిస్తుంది. Exit 0 వద్ద debug log తప్ప మరెక్కడా ఏదీ నివేదించబడదు. మీ profileలోని ఏదైనా echo ను interactive shellsలో మాత్రమే అమలయ్యేలా చుట్టండి.
• ఇంకా సమస్య పరిష్కారం కాకపోతే, 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 ను అమలు చేయకుండా ఎలా ఆపాలి?

PreToolUse hook ను నమోదు చేయండి. అందులో Bash matcher ద్వారా .tool_input.command నుంచి command చదివి, stderr కు కారణాన్ని రాసి, 2 తో exit చేయాలి. 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 చేస్తోంది, కానీ ఏమీ జరగడం లేదు. ఎందుకు?

అత్యంత సాధారణ కారణం మీ shell profile. args field లేని hook sh -c ద్వారా అమలవుతుంది. కొన్ని profiles ప్రతి shell ప్రారంభంలో banner ను print చేస్తాయి. అది మీ JSON కు ముందు stdout లో చేరుతుంది. Output ఇక { తో ప్రారంభం కాకపోవడంతో Claude Code మొత్తం output ను plain text గా పరిగణించి decision ను విస్మరిస్తుంది. Exit 0 అయినప్పుడు transcript లో ఏదీ report చేయదు. మీ 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 ను పరిమిత sudo policy కలిగిన ప్రత్యేక unprivileged account గా అమలు చేయండి. Workspace trust dialog ను అంగీకరించే ముందు ఏ repository లోని hooks block ను అయినా చదవండి, ఎందుకంటే project hooks .claude/settings.json లో ఉంటాయి. వాటిలో ఏదీ అమలు కాకూడదనుకుంటే మీ settings file లో "disableAllHooks": true ను సెట్ చేయండి.