Claude Code Stop Hook: “पूरा” से पहले जाँच

Claude Code का “पूरा” संदेश केवल यह बताता है कि agent इस turn को समाप्त करना चाहता है। इससे न तो यह साबित होता है कि test चला था, न यह कि build artifact नया है। Stop Hook समाप्ति से ठीक पहले एक छोटा local check चला सकता है और कोई साफ़ शर्त fail होने पर बातचीत जारी रख सकता है। यह CI, पूरी test suite या मानवीय approval का विकल्प नहीं है।

Stop Hook, CLAUDE.md और CI की भूमिकाएँ अलग हैं

• Stop Hook response के अंत में छोटा check चलाता है: git diff --check, focused test या अपेक्षित file की मौजूदगी।
• CLAUDE.md agent को पालन करने वाले rules और commands बताता है, लेकिन यह file खुद कोई command नहीं चलाती।
• CI push या pull request के बाद अलग environment में चलती है। टीम के लिए अनिवार्य gate CI ही रहता है।

इस hook में deploy, publish या external service में write न रखें। हर turn के अंत में चलने वाले ऐसे side effect को fail होने पर दोहराना या वापस लेना मुश्किल होता है।

सत्यापित किया जा सकने वाला परिणाम तय करें

hook लिखने से पहले चार बिंदुओं का contract बनाएँ:

1. दावा: turn के बाद agent क्या कह सकता है, जैसे “build बन गया है”।
2. सबूत: कौन-सा command या file इसे साबित करेगा, जैसे npm test -- --runInBand और test -s dist/app.js।
3. सफलता: दोनों checks exit code 0 के साथ समाप्त हों।
4. Stop को रोकना: failure पर hook decision: "block" और छोटा reason वाला JSON लौटाए।

पहले इन commands को hook के बिना चलाएँ। अगर वे कई मिनट लेते हैं या network पर निर्भर हैं, तो उन्हें focused local check तक सीमित करें; पूरा run CI में रखें।

अगर Claude Code API provider के जरिए जुड़ा है, तो पहले BetterToken का मौजूदा setup guide खोलें, tool में अपनी API Key configure करें और एक छोटा test request भेजें। फिर Dashboard में अपेक्षित model, status और token usage जाँचें। Local hook को key की जरूरत नहीं होती; उसे hook log में कभी न लिखें।

न्यूनतम Stop Hook कॉन्फ़िगर करें

.claude/settings.json में short timeout के साथ project hook जोड़ें:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/check-before-stop.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Check को scripts/check-before-stop.sh के रूप में रखें। नीचे दिए commands Node project का उदाहरण हैं; इन्हें अपने repository में मौजूद commands और paths से बदलें।

#!/usr/bin/env sh
set -eu

if [ -t 0 ]; then
  input='{"stop_hook_active":false}'
else
  input=$(cat)
fi

stop_hook_active=$(printf '%s' "$input" | node -e '
let raw = "";
process.stdin.on("data", chunk => raw += chunk);
process.stdin.on("end", () => {
  try { process.stdout.write(String(Boolean(JSON.parse(raw).stop_hook_active))); }
  catch { process.stdout.write("false"); }
});')

block_stop() {
  if [ "$stop_hook_active" = "true" ]; then
    printf '%s\n' "Stop check अभी भी fail हो रहा है: $block_reason. इसे manually चलाएँ; CI अब भी अनिवार्य है।" >&2
    exit 0
  fi

  BLOCK_REASON="$block_reason" node -e 'process.stdout.write(JSON.stringify({decision:"block",reason:`Stop check fail हुआ: ${process.env.BLOCK_REASON}`}) + "\n")'
  exit 0
}

if ! npm test -- --runInBand >/dev/null 2>&1; then
  block_reason='npm test चलाएँ और failed test को ठीक करें'
  block_stop
fi

if ! test -s dist/app.js; then
  block_reason='dist/app.js को फिर से बनाएँ'
  block_stop
fi

printf '%s\n' 'Stop check पास: tests और dist/app.js'
exit 0

File को executable बनाएँ:

chmod +x scripts/check-before-stop.sh

Claude Code की मौजूदा documentation के अनुसार Stop Hook code 0 के साथ structured JSON लौटा सकता है: decision: "block" turn को समाप्त होने से रोकता है और reason कारण बताता है। Non-zero code और timeout की अलग hook-error semantics हैं; इन्हें अकेला blocking contract न बनाएँ। Check configured limit में पूरा होना चाहिए।

अगली बार समाप्ति की कोशिश में, अगर Claude Code पहले से Stop Hook के कारण चल रहा है तो stop_hook_active का मान true होगा। उदाहरण की fail-open branch उसी failure को फिर block करने के बजाय stderr में छोटी warning लिखकर 0 लौटाती है। इससे loop रुकता है, लेकिन CI की सीमा हटती नहीं। बार-बार block करना हो तो अपना counter और स्पष्ट सीमा बनाएँ; किसी undocumented fixed retry count पर निर्भर न रहें।

पूरा चक्र manually सत्यापित करें

सिर्फ यह न देखें कि script terminal में शुरू हो जाता है; हर branch को जाँचें:

1. Script में dist/app.js को अस्थायी रूप से dist/missing.js में बदलें और printf '%s\n' '{"stop_hook_active":false}' | ./scripts/check-before-stop.sh; echo $? चलाएँ। "decision":"block", छोटा reason और code 0 वाला JSON अपेक्षित है।
2. सही path वापस लाएँ, build बनाएँ और वही command फिर चलाएँ। अपेक्षित result code 0 है।
3. फिर से missing file सेट करें, Claude Code से छोटा और reversible बदलाव करने को कहें और जाँचें कि decision: "block" बातचीत को चालू रखता है तथा check का कारण लौटाता है।
4. Path सुधारे बिना printf '%s\n' '{"stop_hook_active":true}' | ./scripts/check-before-stop.sh; echo $? चलाएँ। Script को stderr में छोटी warning और code 0 लौटाना चाहिए। इससे anti-loop branch की जाँच हो जाती है।
5. Path बहाल करें या नया artifact बनाएँ। अगली समाप्ति पर hook को 0 लौटाना चाहिए और turn समाप्त होने देना चाहिए।

यह परीक्षण काम करने वाले Stop Hook और ऐसे script में अंतर बताता है जो terminal में तो fail होता है, लेकिन Claude Code को रुकने देता है।

Block हुए Stop से ठीक तरह recover करें

दो मामलों को अलग रखें। अगर hook decision: "block" वाला JSON लौटाता है, तो reason पढ़ें: जाँची गई condition सामान्य रूप से fail हुई है। वही check manually चलाएँ, test या code ठीक करें, पुष्टि करें कि file current command से बनी है और Claude Code task दोहराएँ।

अगर hook command खुद non-zero code या timeout से समाप्त होती है, तो यह hook execution error है, reason से साबित block नहीं। Error और stderr पढ़ें, script manually चलाएँ और दोबारा जाँचने से पहले path, permissions, dependency या time budget ठीक करें।

Log में केवल check का नाम और result रखें। API Key, .env की contents, पूरा prompt या पूरे test logs न छापें। git diff --check का pass होना business logic को साबित नहीं करता और file का होना नया build साबित नहीं करता। Hook केवल उन्हीं दावों को जाँच सकता है जिन्हें आपने साफ़ तौर पर code में रखा है।

API workflow अलग रखें

API provider के साथ Key को अपने account में बनाएँ और प्रबंधित करें। Stop Hook local ही रहता है: उसे Key, पूरे prompts या Dashboard logs तक पहुँच की जरूरत नहीं है। API incident होने पर Base URL और configuration के लिए current documentation देखें; इस diagnosis को local completion check के साथ न मिलाएँ।

स्रोत

• Claude Code Hooks Reference — 22 अगस्त 2026 को जाँचा गया
• BetterToken: Claude Code कॉन्फ़िगर करें