Claude Code Hooks गाइड: काम से पहले और बाद में सुरक्षित जांच

Claude Code Hooks वे automatic checks हैं जो Claude Code के किसी काम से पहले या बाद में चलते हैं। हर prompt में बार-बार “खतरनाक command मत चलाना”, “file edit के बाद format करना”, “test भी चलाना” लिखने के बजाय आप ये नियम project workflow में लगा सकते हैं।

शुरुआत के लिए आसान मॉडल यह है: PreToolUse brake है, PostToolUse maintenance है, UserPromptSubmit entry log है, और Stop final check है। Hooks human review, permissions, या CI की जगह नहीं लेते। वे बस repeated checks को भूलना मुश्किल बनाते हैं।

यह लेख Claude Code Hooks official reference और Claude Code settings official docs पर आधारित है। Project context के लिए CLAUDE.md best practices पढ़ें, और सुरक्षा design के लिए Claude Code permissions guide देखें।

पहले ये 4 events समझें

Claude Code में कई Hook events हैं, लेकिन practical workflow के लिए शुरुआत इन चार से करें।

Event	कब उपयोग करें	Example
UserPromptSubmit	prompt Claude तक जाने से पहले	request log करना, secret detect करना, हल्का context जोड़ना
PreToolUse	tool चलने से ठीक पहले	destructive Bash command या production action रोकना
PostToolUse	tool चलने के बाद	formatter, lint, related tests चलाना
Stop	Claude response खत्म करने से पहले	Git conflict check, summary save, missing verification reminder

अगर action बिल्कुल नहीं होना चाहिए, तो PreToolUse सही जगह है। अगर action हो चुका है और अब cleanup या verification चाहिए, तो PostToolUse ठीक है। Request quality समझनी हो तो UserPromptSubmit उपयोग करें। Session obvious समस्या के साथ खत्म न हो, तो Stop काम आता है।

Shared rules आमतौर पर .claude/settings.json में रखे जाते हैं। Personal experiment के लिए .claude/settings.local.json बेहतर है, ताकि वह repository में commit न हो। Team में यह भी लिखना चाहिए कि कौन सा Hook block करता है, कौन सा सिर्फ log करता है, और ownership किसकी है।

Copy-paste starter configuration

नीचे की setting prompts save करती है, dangerous Bash commands रोकती है, edit के बाद quality checks चलाती है, और अंत में summary save करती है।

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/log-prompt.mjs"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/block-dangerous-command.mjs"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/run-quality-checks.mjs",
            "timeout": 120
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/stop-summary.mjs"
          }
        ]
      }
    ]
  }
}

यहाँ important बात nested hooks array है। Modern structure में event, optional matcher, और फिर type: "command" जैसे handlers होते हैं। पुराने examples में command को सीधे matcher के पास रखा गया हो सकता है, लेकिन आज वही copy करना अच्छा idea नहीं है।

Use case 1: PreToolUse से dangerous command रोकना

पहला real-world use case command safety है। Agent तेज काम करता है, इसलिए सबसे risky moment command चलने के बाद नहीं, बल्कि command चलने से ठीक पहले होता है। PreToolUse Bash input पढ़कर dangerous operation deny कर सकता है।

इसे .claude/hooks/block-dangerous-command.mjs के रूप में save करें।

import fs from "node:fs";

const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
const command = String(input.tool_input?.command || "");

const denyPatterns = [
  /rm\s+-rf\s+(\/|\*|\.|\$HOME)/i,
  /cat\s+\.env(\.|$|\s)/i,
  /printenv/i,
  /aws\s+.*\s+delete-/i,
  /gcloud\s+.*\s+delete/i,
  /kubectl\s+delete\s+(namespace|deployment|secret)/i,
  /DROP\s+DATABASE/i
];

const matched = denyPatterns.find((pattern) => pattern.test(command));

if (matched) {
  console.log(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: `Blocked by project hook: ${matched}`
    }
  }));
  process.exit(0);
}

यह complete security product नहीं है। Regex को bypass किया जा सकता है। फिर भी यह common mistakes रोकता है: .env पढ़ना, बड़े folder हटाना, cloud resource delete करना, Kubernetes object हटाना, या destructive SQL चलाना। Production में इसे Claude Code permissions, protected branches, CI, और human approval के साथ उपयोग करें।

Use case 2: UserPromptSubmit से prompt log करना

दूसरा use case prompt observability है। कई खराब Claude Code sessions model की वजह से नहीं, बल्कि vague request की वजह से शुरू होते हैं: “fix this”, “clean this”, “make it better”. Log होने पर आप देख सकते हैं कि कौन सा prompt pattern अच्छा काम करवाता है।

इसे .claude/hooks/log-prompt.mjs के रूप में save करें।

import fs from "node:fs";
import path from "node:path";

const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
const dir = path.join(process.cwd(), ".claude", "hook-logs");
fs.mkdirSync(dir, { recursive: true });

const record = {
  time: new Date().toISOString(),
  event: input.hook_event_name,
  cwd: input.cwd,
  prompt: input.prompt || input.user_prompt || ""
};

fs.appendFileSync(
  path.join(dir, "prompts.jsonl"),
  JSON.stringify(record) + "\n",
  "utf8"
);

यह log पहले local रखें। Prompts में customer name, internal URL, गलती से pasted token, या business context हो सकता है। .claude/hook-logs/ को .gitignore में जोड़ें और retention, access, ownership पहले तय करें।

Use case 3: edit के बाद format और test चलाना

तीसरा use case रोज का quality workflow है। Claude किसी file को edit करे तो formatter और छोटा verification command चले। इससे हर prompt में “format and test” लिखने की जरूरत कम होती है।

इसे .claude/hooks/run-quality-checks.mjs के रूप में save करें।

import fs from "node:fs";
import { execFileSync } from "node:child_process";

const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
const filePath = String(input.tool_input?.file_path || "");

const isSourceFile = /\.(js|jsx|ts|tsx|css|md|mdx|json)$/.test(filePath);
if (!isSourceFile) process.exit(0);

const run = (cmd, args) => {
  try {
    return execFileSync(cmd, args, {
      cwd: process.cwd(),
      encoding: "utf8",
      stdio: ["ignore", "pipe", "pipe"]
    });
  } catch (error) {
    return String(error.stdout || "") + String(error.stderr || "");
  }
};

const messages = [];
messages.push(run("npx", ["prettier", "--write", filePath]));

if (/\.(js|jsx|ts|tsx)$/.test(filePath)) {
  messages.push(run("npm", ["test", "--", "--runInBand"]));
}

console.log(JSON.stringify({
  hookSpecificOutput: {
    hookEventName: "PostToolUse",
    additionalContext: messages.join("\n").slice(-4000)
  }
}));

Large monorepo में हर edit पर full test suite न चलाएँ। पहले format, फिर related tests, और heavy checks को async Hook या CI में भेजें। Claude को लौटाई गई output भी cut करें, वरना context logs से भर जाएगा।

Use case 4: Stop में final check

Stop तब चलता है जब Claude response खत्म करने वाला होता है। यहाँ भारी test चलाने के बजाय clear unfinished state रोकना अच्छा है, जैसे unresolved Git conflict।

import fs from "node:fs";
import { execFileSync } from "node:child_process";

const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");

if (input.stop_hook_active) {
  process.exit(0);
}

let status = "";
try {
  status = execFileSync("git", ["status", "--short"], {
    cwd: process.cwd(),
    encoding: "utf8"
  });
} catch {
  process.exit(0);
}

if (status.includes("UU ")) {
  console.error("Git conflict remains. Resolve conflicts before finishing.");
  process.exit(2);
}

fs.mkdirSync(".claude/hook-logs", { recursive: true });
fs.appendFileSync(
  ".claude/hook-logs/stop.jsonl",
  JSON.stringify({
    time: new Date().toISOString(),
    lastAssistantMessage: input.last_assistant_message || "",
    gitStatus: status.slice(0, 2000)
  }) + "\n"
);

Stop hook को बहुत strict न बनाएं। ज्यादा block करने पर agent बार-बार खत्म करने की कोशिश करेगा। stop_hook_active check करें, condition narrow रखें, और शुरुआत में blocking से ज्यादा logging करें।

Pitfall: common mistakes और बचाव

पहला pitfall है Hooks को permissions का replacement मान लेना। Command hook आपके system user की permission से चलता है। खराब script secret पढ़ सकता है या file delete कर सकता है। Input validate करें, path traversal रोकें, .env और .git से दूर रहें।

दूसरा pitfall है synchronous Hook में बहुत काम डालना। एक file format करना ठीक है। हर edit पर build, full test, browser test और deploy भारी हो जाएगा। Fast checks PostToolUse में रखें, slow checks async या CI में भेजें।

तीसरा pitfall है log policy के बिना logging। Logs debug में मदद करते हैं, पर sensitive data भी रख सकते हैं। Location, retention, access, और Git exclusion तय करें।

चौथा pitfall है matcher को business logic समझना। matcher: "Bash" सिर्फ Bash events को handler तक भेजता है। वास्तविक allow/deny decision script को command पढ़कर करना होगा।

Masa-style verification note

Testing में सबसे बड़ा benefit additionalContext से format और test output Claude को वापस देने से मिला। Claude अगले step में error खुद देख सकता है, इसलिए इंसान को log paste करने की जरूरत कम हुई। Dangerous command block भी उपयोगी है, क्योंकि वह obvious mistake को सही समय पर रोकता है।

Team में पहली बार लागू करते समय मैं तीन चरण रखूंगा: पहले एक सप्ताह prompt logs, फिर edit के बाद format, फिर छोटी deny list for Bash. इस order से trust बनता है और friction कम रहता है।

अगर आप permissions, CLAUDE.md, Hooks, और review workflow को team में साथ में set up करना चाहते हैं, तो Claude Code training page देखें। Solo developer के लिए यही pattern Gumroad checklist बन सकता है, ताकि हर नए project में repeatable setup मिले।

Summary

Claude Code Hooks practical guardrails हैं। UserPromptSubmit request समझने के लिए, PreToolUse risky action रोकने के लिए, PostToolUse changes verify करने के लिए, और Stop obvious unfinished work रोकने के लिए उपयोग करें।

छोटे से शुरू करें। ऐसा simple Hook जो हर कोई चालू रखे, उस बड़े automation से बेहतर है जिसे दो दिन बाद disable कर दिया जाए।