SSD Nodes Learn Hosting plans →
تعلیمی Matt Connorتحریر: Matt Connor

Claude Code hooks: events، exit code 2 اور سیکیورٹی

Claude Code hooks model کی رضامندی کے بغیر چلتے ہیں۔ جانیں یہ کہاں درج ہوتے ہیں، کون سے events fire ہوتے ہیں، exit code 2 tool call کیوں روکتا ہے اور سیکیورٹی لاگت کیا ہے۔

Claude Code hook کیا ہے

Claude Code hooks وہ shell commands ہیں جنہیں Claude Code اپنے lifecycle کے مخصوص مقامات پر خود بخود چلاتا ہے۔ یہی ایک hook اور rules file کے درمیان بنیادی فرق ہے۔ CLAUDE.md میں موجود ہدایت ایک مشورہ ہے، اور ماڈل اپنے context میں موجود دیگر تمام عوامل کے ساتھ اس کا موازنہ کرتا ہے۔ ایک hook کوڈ ہوتا ہے، اور یہ اس بات سے قطع نظر چلتا ہے کہ ماڈل اس سے متفق ہے یا نہیں۔ اگر آپ کا ایجنٹ اس فارمیٹر کو نظر انداز کر رہا ہے جس کے بارے میں آپ نے اسے دو بار بتایا ہے، تو آپ کو مزید سخت ہدایت کی ضرورت نہیں ہے۔ آپ کو ایک hook کی ضرورت ہے۔

یہ میکانزم مختصر ہے۔ آپ settings file میں ایک event name کے تحت کمانڈ رجسٹر کرتے ہیں۔ جب وہ event متحرک ہوتا ہے، تو Claude Code آپ کی کمانڈ چلاتا ہے اور event ڈیٹا کو standard input (stdin) پر JSON (JavaScript object notation) کی شکل میں لکھتا ہے۔ آپ کی کمانڈ اس ڈیٹا کو پڑھتی ہے، اپنا کام کرتی ہے، اور exit status کے ساتھ جواب دیتی ہے۔ PreToolUse hook سے exit 2 ٹول کال کو چلنے سے پہلے منسوخ کر دیتا ہے، اور آپ کی اسکرپٹ نے standard error (stderr) پر جو کچھ لکھا ہوتا ہے وہ ماڈل کو وجہ کے طور پر واپس بھیج دیا جاتا ہے، سوائے اس کے کہ hook کوئی ایسا JSON بھی پرنٹ کرے جس میں blocking فیصلہ شامل ہو، جس کی وجہ کو ترجیح دی جاتی ہے۔

یہاں ایونٹ کے نام اور فیلڈ کے نام Claude Code hooks reference سے لیے گئے ہیں، جنہیں 12 نومبر 2026 کو چیک کیا گیا تھا۔ یہ سطح تیزی سے تبدیل ہوتی ہے، لہذا کسی بھی بلاگ پوسٹ سے JSON کاپی کرنے سے پہلے، بشمول اس کے، اپنے ورژن کے لیے reference کو ضرور چیک کریں۔ اپنا ورژن claude --version کے ساتھ پرنٹ کریں۔

ہُک کی configuration کہاں موجود ہوتی ہے

ہُک settings file میں موجود ایک JSON block ہوتا ہے۔ چھ مقامات پر ہُک رکھا جا سکتا ہے، اور file کا scope ہی ہُک کا scope ہوتا ہے۔

  • ~/.claude/settings.json: آپ کے تمام projects کے لیے، اور کسی دوسرے شخص کے project کے لیے نہیں۔
  • .claude/settings.json: ایک project کے لیے؛ یہ repository میں commit ہوتا ہے، اس لیے اسے clone کرنے والے ہر شخص کو یہ ہُک مل جاتا ہے۔
  • .claude/settings.local.json: ایک project کے لیے، صرف آپ کی machine پر۔
  • Managed policy settings: پوری organisation کے لیے، administrator کے ذریعے set کی جاتی ہیں۔
  • hooks/hooks.json: plugin کے اندر؛ یہ صرف اس وقت فعال رہتا ہے جب وہ plugin enabled ہو۔
  • Skill یا subagent frontmatter۔ Skill invoke ہونے کے بعد اس کے hooks session کے باقی حصے تک فعال رہتے ہیں، جبکہ subagent کے hooks اس وقت تک فعال رہتے ہیں جب تک وہ subagent چل رہا ہو۔

ان files سے آنے والی hook entries ایک دوسرے کو override کرنے کے بجائے merge ہو جاتی ہیں۔ Project settings file اپنے hooks کو آپ کی user settings میں موجود hooks کے ساتھ شامل کرتی ہے، انہیں replace نہیں کرتی۔ اس لیے ایک event میں متعدد files سے آنے والے کئی hooks ہو سکتے ہیں۔ "disableAllHooks": true set کرنے سے یہ hooks بند ہو جاتے ہیں۔ ایک استثنا ہے: Managed policy settings سے آنے والے hooks چلتے رہتے ہیں، جب تک وہ setting managed settings میں بھی apply نہ کی جائے۔

Session کے اندر /hooks چلائیں تاکہ اس وقت registered تمام hooks کی فہرست event کے لحاظ سے گروپ شدہ شکل میں دیکھ سکیں۔ ہر hook کے لیے source file اور matcher بھی دکھایا جاتا ہے۔ یہ menu read-only ہے، اس لیے hook تبدیل کرنے کے لیے settings file edit کریں۔ File watcher عموماً restart کے بغیر edit کو پہچان لیتا ہے۔

Claude Code میں کون سے hook events موجود ہیں

Hooks reference میں SessionStart سے SessionEnd تک کل thirty three events درج ہیں۔ ان میں compaction، subagents، worktrees اور configuration files شامل ہیں۔ Server کے کام میں ان میں سے چند events استعمال ہوتے ہیں۔

  • PreToolUse: کسی tool call کے execute ہونے سے پہلے، سوائے EndConversation کے۔ یہی event tool call کو روک سکتا ہے۔
  • PostToolUse: کسی tool call کے کامیاب ہونے کے بعد، سوائے EndConversation کے۔ ناکامی کی صورت میں PostToolUseFailure چلتا ہے۔ اس لیے ہر outcome دیکھنے والے hook کو دونوں events درکار ہوتے ہیں۔
  • PermissionRequest: جب کسی tool call کے لیے permission decision درکار ہو۔ اسی وقت approval prompt ظاہر ہونے والا ہوتا ہے۔
  • UserPromptSubmit: جب آپ prompt submit کرتے ہیں، Claude کے اسے process کرنے سے پہلے۔ کامیاب hook کا plain-text stdout model کے context میں شامل کر دیا جاتا ہے۔
  • SessionStart اور SessionEnd: session کے ہر اختتام پر۔ compaction کے بعد SessionStart بھی چلتا ہے، جس کے لیے matcher value compact ہوتی ہے۔
  • Stop: جب Claude جواب دینا مکمل کرتا ہے۔ یہ ہر turn کے بعد ایک بار چلتا ہے، ہر مکمل task کے بعد نہیں۔

جن events میں matchers کی سہولت ہو، ان میں ایک group ایسا matcher رکھ سکتا ہے جو طے کرتا ہے کہ کن occurrences پر hook چلے گا۔ Tool events میں یہ 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 کو پکڑتا ہے اور باقی کو الگ رکھتا ہے۔

Stop hooks میں ایک اہم احتیاط ہے جسے hook لکھنے سے پہلے سمجھنا ضروری ہے۔ جو Stop hook block کرتا ہے، وہ model کو دوبارہ کام کرنے کے لیے بھیج دیتا ہے۔ پہلے سے طے شدہ طور پر Claude Code مسلسل آٹھ continuations کے بعد اگلے block کو override کر دیتا ہے۔ جب بھی Claude کسی tool کو call کرتا ہے، count دوبارہ شروع ہو جاتا ہے۔ Hook input سے stop_hook_active field پڑھیں اور جب اس کی قدر 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 شامل ہوتے ہیں۔ دیگر 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 فیصلہ جاتی fields بدستور لاگو رہتی ہیں، جن میں block یا denial بھی شامل ہے۔ PreToolUse پر، کسی decision کے بغیر exit 0 منظوری نہیں ہوتا، اور معمول کا permission flow پھر بھی چلتا ہے۔ UserPromptSubmit، UserPromptExpansion، SessionStart اور PostModelSwitch پر plain-text stdout کو model کے context میں شامل کیا جاتا ہے۔ زیادہ تر دیگر events پر stdout صرف debug log میں جاتا ہے۔
  • Exit 2 ان events پر action کو block کرتا ہے جنہیں block کیا جا سکتا ہے، اور PreToolUse بھی ان میں شامل ہے۔ stderr وہ message بن جاتا ہے جو block کے ساتھ دکھایا جاتا ہے، سوائے اس کے کہ JSON output میں blocking decision موجود ہو؛ ایسی صورت میں اس decision کی reason کو ترجیح حاصل ہوتی ہے۔ یہ message کون پڑھتا ہے، اس کا انحصار 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، اگر stdout plain-text یا empty ہو، تو عموماً non-blocking error ہوتا ہے۔ Transcript میں hook error notice دکھایا جاتا ہے، جس میں Failed with non-blocking status code: کے بعد stderr کی پہلی line شامل ہوتی ہے۔ PreToolUse جیسے events پر درست JSON پھر بھی نتیجہ طے کر سکتا ہے، الاّ یہ کہ hook کی failure action کو block کرتی ہو۔ WorktreeCreate کسی بھی nonzero exit پر fail ہوتا ہے، جبکہ WorktreeRemove nonzero exit پر اسی وقت fail ہوتا ہے جب اس کے بعد directory موجود رہے۔

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 کو skip کرتا ہے، بشرطیکہ permission rules اور tool کی approval requirements اس کی اجازت دیں۔ "deny" call کو cancel کرتا ہے اور reason model کو بھیجتا ہے۔ "ask" confirmation طلب کرتا ہے۔ ہر hook کے لیے ایک ہی style منتخب کریں۔ stdout پر JSON decision کے ساتھ exit 2 استعمال کرنے سے block برقرار رہتا ہے، خواہ JSON میں "allow" درج ہو۔

جب ایک event سے کئی hooks مطابقت رکھتے ہوں تو وہ parallel چلتے ہیں۔ prompt اور agent hooks کو بیک وقت زیادہ سے زیادہ بارہ running hooks تک محدود رکھا جاتا ہے۔ ایک hook کا deny اس کے siblings کو نہیں روکتا؛ اس لیے logging hook اپنی line لکھتا رہتا ہے جبکہ guardrail hook اسی call کو deny کرتا ہے۔ PreToolUse کے لیے Claude Code پھر تمام answers کو merge کرتا ہے اور سب سے restrictive نتیجہ برقرار رکھتا ہے۔ ترجیح کی ترتیب deny، defer، ask، allow ہے۔

مثال 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 پر 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 کریں، کیونکہ جب onFailure unset ہو تو ایسا hook جو اپنے input پر crash ہو جائے، عموماً fail open ہو جاتا ہے۔ Windows پر Git Bash کے بغیر، ناکام 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 جیسی بے ضرر command دیں؛ آپ کو کوئی output نہیں ملنا چاہیے اور exit code 0 ہونا چاہیے۔ session میں denied call transcript میں آپ کے message کو وجہ کے طور پر دکھاتی ہے، اور model اس message کو پڑھ کر اپنا طریقہ بدل لیتا ہے۔

ایک خصوصیت اس عمل کو مفید بناتی ہے: PreToolUse hooks ہر permission mode میں permission-mode check سے پہلے fire ہوتے ہیں، اس لیے bypassPermissions کے تحت بھی deny مؤثر رہتا ہے۔ یہی وجہ ہے کہ hook Claude Code کے auto mode اور اس کی permission settings کے ساتھ مفید ہے؛ prompts کم ہو جاتے ہیں، لیکن hook پھر بھی fire ہوتا ہے۔

اس کی حدود کے بارے میں واضح رہیں۔ command string پر pattern matching کسی agent کی لاپروائی کے خلاف guardrail ہے۔ یہ کسی clever agent کے خلاف boundary نہیں ہے، کیونکہ وہی command ایسی شکل میں لکھی جا سکتی ہے جسے آپ کا grep کبھی نہیں دیکھتا۔ سخت rules permission system میں اور اس account میں ہونے چاہئیں جس کے تحت process چلتا ہے۔

مثال 2: ہر ترمیم کے بعد 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
          }
        ]
      }
    ]
  }
}

Claude سے کہیں کہ وہ Python file میں غلط indentation والا function شامل کرے، پھر file کھولیں۔ file formatted حالت میں واپس آتی ہے۔ یہی اس بات کی تصدیق ہے کہ hook چلا، کیونکہ کامیاب hook گفتگو میں کچھ ظاہر نہیں کرتا۔

یہاں exit 2 کسی چیز کو واپس نہیں کرتا۔ PostToolUse tool کے پہلے ہی execute ہونے کے بعد چلتا ہے، اس لیے edit دونوں صورتوں میں disk پر موجود رہتی ہے۔ exit 2 کا فائدہ یہ ہے کہ ruff check کا output model تک feedback کے طور پر پہنچتا ہے، لہٰذا وہ ابھی پیدا کی گئی error کو درست کر دیتا ہے اور آگے نہیں بڑھتا۔ یہی اس lint failure کا فرق ہے جس کا آپ کو commit کے وقت پتا چلتا ہے، اور اس failure کا جسے agent اسی turn میں درست کر دیتا ہے۔

یہاں دو matcher limits اہم ہیں۔ Edit|Write کو shell command سے تبدیل ہونے والی files نظر نہیں آتیں، اور Claude اتنی کثرت سے Bash کے ذریعے files لکھتا ہے کہ یہ خلا حقیقی مسئلہ بن جاتا ہے۔ ہر call کے لیے coverage حاصل کرنے کی خاطر Bash سے بھی match کریں اور script سے کہیں کہ وہ git status --porcelain کے ذریعے تبدیل ہونے والی files کی فہرست بنائے۔ ہر turn میں ایک بار coverage کے لیے scan کو Stop hook میں رکھیں۔

مثال 3: audit کے لیے ہر tool call کا log درج کریں

PostToolUse پر خالی matcher، EndConversation کے علاوہ ہر کامیاب tool call پر عمل کرتا ہے۔ record کو home directory کی file کے بجائے system journal میں بھیجنے سے یہ agent کے اپنے shell کی رسائی سے محفوظ نہیں ہو جاتا: رسائی account کی permissions پر منحصر ہوتی ہے۔ Users اپنی private per-user journals پڑھ سکتے ہیں، جبکہ root اور systemd-journal، adm یا wheel کے ارکان تمام 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 نظر آنی چاہیے، جس میں تازہ ترین line آخر میں ہو۔ اگر کچھ ظاہر نہ ہو تو journal access کے ساتھ یہ بھی جانچیں کہ hook چلا تھا یا نہیں؛ نیچے troubleshooting section میں hook کا جائزہ دیا گیا ہے۔

ناکام calls capture کرنے کے لیے PostToolUseFailure کے تحت یہی block شامل کریں، کیونکہ PostToolUse صرف کامیابی پر عمل کرتا ہے اور ناکام command عموماً زیادہ اہم ہوتی ہے۔ logger کو home directory کی file میں append کرنے کے بجائے استعمال کرنے کی وجہ ownership ہے: hook agent کے shell والے ہی user کے طور پر چلتا ہے، اس لیے جس چیز میں وہ user append کر سکتا ہے اسے truncate بھی کر سکتا ہے۔ Journal systemd-journald میں لکھا جاتا ہے؛ اسے deletion سے محفوظ رکھنا پھر بھی 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 کو default طور پر 600 سیکنڈ ملتے ہیں، یعنی دس منٹ۔ کچھ events اس مدت کو نمایاں طور پر کم کر دیتے ہیں۔ SessionEnd hooks کے درمیان مجموعی طور پر 1.5 سیکنڈ کا budget مشترک ہوتا ہے، اس لیے session ختم ہونے پر ہونے والی cleanup تیز ہونی چاہیے۔ تاہم settings files میں کسی hook کے لیے زیادہ لمبا timeout مقرر کرنے سے یہ مشترک budget بھی اسی قدر بڑھ جاتا ہے، زیادہ سے زیادہ 60 سیکنڈ تک۔

اگر synchronous command، HTTP یا MCP tool hook timeout تک پہنچ جائے تو اسے cancel کر دیا جاتا ہے اور عموماً کوئی فیصلہ render نہیں ہوتا؛ PreModelSwitch پر timeout switch کو روک دیتا ہے۔ PreToolUse guardrail کے لیے timeout عموماً tool call کو معمول کے permission flow میں آگے بڑھنے دیتا ہے، تاہم اوپر بیان کردہ Windows exception اس وقت لاگو ہوتی ہے جب onFailure unset ہو۔ اسی وجہ سے 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 کام کے لیے جس کا کوئی منتظر نہ ہو، مثلاً log کو کسی اور جگہ بھیجنے کے لیے، "async": true مقرر کریں۔ اس طرح hook background میں چلتا ہے اور tool call کو روکتا نہیں۔

Hooks، rules files، skills اور MCP servers

یہ چاروں چیزیں ایک دوسرے سے اس لیے خلط ملط ہو جاتی ہیں کہ یہ سب agent کے طرزِ عمل کو تبدیل کرتی ہیں۔ ان میں صرف ایک چیز suggestion نہیں رہتی۔

rules file (CLAUDE.md، یا .claude/rules/ کے اندر موجود file) وہ متن ہے جو model کے context میں load ہوتا ہے۔ یہ طرزِ عمل کو shape کرتی ہے، لیکن کسی چیز کو enforce نہیں کرتی۔ ایک طویل conversation، بڑے diff اور user کی نئی request کے مقابلے میں اس کی ایک سطر نظرانداز ہو سکتی ہے۔ یہی عام طریقہ ہے جس کے باعث agents آپ کی لکھی ہوئی instructions کو نظرانداز کرتے ہیں۔

skill، instructions اور scripts کا ایک folder ہوتی ہے جسے model اس وقت load کرتا ہے جب اسے skill متعلقہ معلوم ہو۔ یہی فیصلہ skill کا بنیادی مقصد ہے، اور یہی اس کی حد بھی ہے: فیصلہ پھر بھی model ہی کرتا ہے۔ اس کی دونوں جہتیں Ponytail، جو agent کو کام کرنے والی کم سے کم تبدیلی کی طرف لے جاتا ہے جیسی skill میں نظر آتی ہیں، کیونکہ یہ پورے task سے نمٹنے کے طریقے کو اس طرح shape کرتی ہے جو کوئی hook نہیں کر سکتا، اور صرف اسی وقت فعال ہوتی ہے جب model اسے load کرنے کا انتخاب کرے۔

MCP (model context protocol) server، model کو call کرنے کے لیے نئے tools فراہم کرتا ہے۔ اس سے agent کی رسائی کا دائرہ وسیع ہوتا ہے۔ لیکن یہ agent کو کسی چیز تک رسائی حاصل کرنے پر مجبور نہیں کرتا۔ مزید یہ کہ یہ ایک الگ process ہے جسے آپ کو operate کرنا پڑتا ہے، اور یہ خود ایک الگ کام ہے: VPS پر MCP servers چلانے کا طریقہ دیکھیں۔

ان چاروں میں صرف hook ایسا ہے جو model کے انتخاب کے بغیر run ہوتا ہے۔ preference کے لیے rules file استعمال کریں، اور اس procedure کے لیے skill استعمال کریں جس پر model کو متعلقہ ہونے کی صورت میں عمل کرنا چاہیے۔ اس step کے لیے hook استعمال کریں جو ہر بار لازماً ہونا چاہیے، یا اس کام کے لیے جو کبھی نہیں ہونا چاہیے۔ مزید تفصیلی موازنہ، جس میں یہ بھی شامل ہے کہ skill کب rules file سے بہتر ہوتی ہے، skills، MCP اور rules files کا موازنہ میں موجود ہے۔

plugin پانچواں mechanism نہیں بلکہ packaging ہے۔ یہ hooks کو skills کے ساتھ ایک installable unit میں bundle کرتا ہے۔ اسی طریقے سے team ہر machine پر ایک ہی guardrail ship کرتی ہے: Claude Code plugins کیسے کام کرتے ہیں دیکھیں۔

مشترکہ VPS پر سیکیورٹی کا فیصلہ

hook وہ کوڈ ہے جسے ایجنٹ ٹرگر کرتا ہے، اور یہ اسی صارف کے طور پر چلتا ہے جس نے Claude Code شروع کیا ہے۔ یہ اس صارف کی file permissions اور environment کا وارث ہوتا ہے۔ لیپ ٹاپ پر یہ workflow کا سوال ہے، لیکن VPS پر جہاں ایجنٹ بغیر نگرانی کے چلتا ہے، یہ چار عملی پہلوؤں کے ساتھ سیکیورٹی کا سوال بن جاتا ہے۔

repository میں موجود hook ایسا کوڈ ہے جسے آپ نے نہیں لکھا۔ .claude/settings.json کمٹ (commit) ہوتا ہے، لہذا repository کو clone کرنا اور اس کے اندر session شروع کرنا ان hooks کو رجسٹر کر سکتا ہے جو repository کے ساتھ آئے تھے۔ ایک interactive session میں، Claude Code پروجیکٹ کے hooks کو اس فولڈر کے لیے workspace trust dialog کے پیچھے رکھتا ہے، جس کا مطلب ہے کہ trust قبول کرنا ہی وہ لمحہ ہے جب آپ انہیں چلانے کا فیصلہ کرتے ہیں۔ پہلے hooks بلاک کو پڑھیں۔ ایک claude -p یا SDK session، جو کہ بغیر نگرانی کے چلنے والے ایجنٹ کا عام طریقہ ہے، کبھی وہ dialog نہیں دکھاتا اور فولڈر کو trusted سمجھتا ہے، اس لیے repository کے hooks بغیر پوچھے چل جاتے ہیں۔ اس کے خلاف اسکرپٹ بنانے سے پہلے اس کی .claude/ فائلیں دیکھ لیں، یا --settings '{"disableAllHooks": true}' کے ساتھ چلائیں۔

hook مکمل tool input دیکھ سکتا ہے۔ ایک audit hook جو tool_input کو لاگ کرتا ہے، ہر command کے ہر argument کو ایک لاگ میں لکھتا ہے، بشمول وہ ٹوکن جو اتفاق سے command line پر موجود ہو۔ اس لاگ کو پھر اسی تحفظ کی ضرورت ہوتی ہے جس کی secret کو ضرورت ہے، جو کہ AI ایجنٹ کی پہنچ سے secrets کو دور رکھنے کے وسیع تر مسئلے کا حصہ ہے۔

hook ماڈل کے context میں لکھ سکتا ہے۔ ایک کامیاب SessionStart یا UserPromptSubmit hook سے حاصل ہونے والا سادہ ٹیکسٹ stdout گفتگو میں شامل کر دیا جاتا ہے۔ ایک ایسا hook جو باہر سے، کسی issue tracker یا log file سے ٹیکسٹ پائپ کرتا ہے، وہ ماڈل کو غیر معتبر ٹیکسٹ ایسے دے رہا ہے جیسے آپ نے خود ٹائپ کیا ہو۔ ایک ایسا hook جو اسی VPS پر کسی دوسرے Claude Code session سے نوٹ فارورڈ کرتا ہے، وہ بھی یہی کام کر رہا ہے، اور ایک ایجنٹ کی آؤٹ پٹ کو issue tracker سے زیادہ قابل اعتماد نہیں سمجھا جا سکتا۔ اس stdout کو آؤٹ پٹ کے بجائے ان پٹ کے طور پر دیکھیں۔

اختیارات (Privilege) ہی اصل کنٹرول ہیں۔ ایجنٹ کو ایک مخصوص غیر مراعات یافتہ صارف (unprivileged user) کے طور پر چلائیں جس کے پاس صرف وہی sudo رولز ہوں جن کی اسے ضرورت ہے۔ PreToolUse deny کا ہونا فائدہ مند ہے، اور یہ ڈیزائن کے لحاظ سے بہترین کوشش (best effort) ہے: reference میں if فلٹر کے بارے میں بھی یہی کہا گیا ہے اور ہدایت کی گئی ہے کہ جب آپ کو سخت پابندی (hard deny) درکار ہو تو permission system کا استعمال کریں۔ permission rules اور وہ اکاؤنٹ جس کے تحت process چلتی ہے، وہی وہ حصے ہیں جو دباؤ میں برقرار رہتے ہیں۔

ایک خصوصیت ہر permission mode میں برقرار رہتی ہے۔ PreToolUse hooks ہر permission mode میں permission-mode چیک سے پہلے چلتے ہیں، لہذا deny واپس کرنے والا hook bypassPermissions کے تحت بھی tool کو بلاک کر دیتا ہے۔ Hooks permission rules کی اجازت کو محدود کر سکتے ہیں، لیکن اسے ڈھیلا نہیں کر سکتے۔ اس کا استثنا ایک mod ہے۔ ایسی مشین پر جس میں کوئی managed settings نہ ہوں اور کوئی managed-mcp.json فائل نہ ہو، اور ایسے session میں جو Team یا Enterprise plan کے لیے /login کے ذریعے سائن ان نہ ہو، ایک انسٹال شدہ mod جو tool.check کو ہینڈل کرتا ہے، اس call کو منظور کر سکتا ہے جسے آپ کے PreToolUse hook نے بلاک کیا تھا۔ Managed settings، managed-mcp.json فائل، یا سیشن کی اسناد کے طور پر Team یا Enterprise /login کے ساتھ، وہ call جسے PreToolUse hook نے بلاک کیا ہو، بائی ڈیفالٹ بلاک ہی رہتی ہے، چاہے hook کسی بھی settings file سے آیا ہو۔ ایک ایسا session جو API key یا طویل مدتی CLAUDE_CODE_OAUTH_TOKEN پر چلتا ہے، جیسا کہ بہت سے سرورز پر ہوتا ہے، سائن ان نہ ہونے کے برابر شمار ہوتا ہے، تب بھی جب login محفوظ ہو۔ سرور پر انسٹال کرنے سے پہلے چیک کریں کہ Claude Code mods کیا تبدیل کر سکتے ہیں۔

میرا hook کیوں نہیں چل رہا؟

اسے اسی ترتیب سے دیکھیں۔ ہر مرحلہ وہ علامت بیان کرتا ہے جو آپ حقیقت میں دیکھیں گے۔

  • /hooks چلائیں اور دیکھیں کہ hook آپ کے متوقع event کے تحت دکھائی دے رہا ہے یا نہیں۔ اگر hook menu میں موجود نہ ہو تو عموماً 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 بھی دیکھیں، کیونکہ valid 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 نے 0 کے ساتھ exit کیا، transcript میں کوئی error نہیں دکھائی دیتا۔ زیادہ تر events پر یہ text صرف debug log میں جاتا ہے، جبکہ UserPromptSubmit، UserPromptExpansion، SessionStart اور PostModelSwitch پر اسے banner سمیت model کے context میں شامل کر دیا جاتا ہے۔ اپنی profile میں کسی بھی echo کو اس طرح wrap کریں کہ وہ صرف 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 ماڈل کے context میں موجود متن ہوتی ہے، اس لیے یہ conversation اور موجودہ request کے ساتھ model کی توجہ کے لیے مقابلہ کرتی ہے، اور model ان سب کے مقابلے میں اس instruction کی اہمیت کا تعین کر سکتا ہے۔ Hook ایک shell command ہوتی ہے جسے Claude Code اپنے lifecycle کے ایک مقررہ مرحلے پر چلاتا ہے، اس لیے event کے ہر وقوع پر یہ لازماً execute ہوتی ہے، خواہ model نے کچھ بھی فیصلہ کیا ہو۔ کسی preference کے لیے instruction استعمال کریں۔ ایسے step کے لیے hook استعمال کریں جو ہمیشہ ہونا چاہیے یا ایسا action جو کبھی نہیں ہونا چاہیے۔

Claude Code کو کسی مخصوص shell command کو چلانے سے کیسے روکوں؟

PreToolUse hook کو ایسے Bash matcher کے ساتھ register کریں جو command کو .tool_input.command سے پڑھتا ہو، stderr میں وجہ لکھتا ہو اور 2 کے ساتھ exit کرتا ہو۔ Claude Code call کو cancel کر دیتا ہے اور model کو آپ کی وجہ دکھاتا ہے۔ یہ permission-mode check سے پہلے ہوتا ہے، اس لیے deny bypassPermissions mode میں بھی مؤثر رہتی ہے۔ Command string پر pattern matching ایک guardrail ہے، security boundary نہیں، کیونکہ وہی command ایسی شکل میں لکھی جا سکتی ہے جسے pattern نہ پکڑ سکے۔ اس لیے اسے permission rules اور unprivileged account کے ساتھ استعمال کریں۔

میری hook درست JSON print کرتی ہے، لیکن کچھ نہیں ہوتا۔ کیوں؟

اپنے shell profile میں ایسا text تلاش کریں جو JSON سے پہلے print ہو رہا ہو۔ macOS اور Linux پر args field کے بغیر hook، sh -c کے ذریعے چلتی ہے۔ ایسے setups میں جو اب بھی profile کو source کرتے ہیں، مثلاً BASH_ENV کا ~/.bashrc کی طرف point کرنا، banner print کرنے والا profile آپ کے JSON سے پہلے stdout پر text لکھ دیتا ہے۔ چونکہ 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 اس user کے طور پر چلتی ہیں جس نے Claude Code شروع کیا ہو، اور اسی user کی file permissions استعمال کرتی ہیں۔ اس لیے hook وہ سب کچھ کر سکتی ہے جو اس account کو کرنے کی اجازت ہو۔ زیادہ تر خطرے سے نمٹنے کے لیے دو عادات کافی ہیں: agent کو محدود sudo policy والے dedicated unprivileged account کے طور پر چلائیں، اور کسی repository کے workspace trust dialog کو accept کرنے یا اس میں claude -p چلانے سے پہلے اس کا hooks block پڑھیں۔ اس کی وجہ یہ ہے کہ project hooks .claude/settings.json کے اندر موجود ہوتی ہیں اور -p mode کبھی یہ dialog نہیں دکھاتا۔ Hooks disable کرنے کے لیے اپنی settings file میں "disableAllHooks": true set کریں، البتہ managed hooks کے لیے یہ setting managed level پر درکار ہوتی ہے۔ false کی project setting، true کی user setting کو override کر سکتی ہے۔

کیا یہ مضمون مفید تھا؟