بدترین بگ آپ کے سسٹم کو کریش نہیں کرتے، بلکہ وہ محض آپ کی بات سے اتفاق کرتے ہیں۔

میں نے یہ سبق ایک مشکل تجربے سے سیکھا جب میں Suhail بنا رہا تھا، جو Claude Code کے اندر پانچ مخصوص subagents کو مربوط کرنے کے لیے ڈیزائن کیا گیا ایک orchestrator تھا۔ ہر ورکر کا ایک الگ کردار تھا: سیاق و سباق جمع کرنے کے لیے ایک researcher، کاموں کو تقسیم کرنے کے لیے ایک planner، کوڈ لکھنے کے لیے ایک coder، آؤٹ پٹ کا معائنہ کرنے کے لیے ایک reviewer، اور ریگریشنز (regressions) چیک کرنے کے لیے ایک auditor۔ آئیڈیا سادہ تھا۔ orchestrator ایک درخواست پڑھے گا، فیصلہ کرے گا کہ کسے کیا کرنا ہے، اور پھر کام کو متوازی (parallel) طور پر بھیج دے گا۔ اس کے بجائے، مجھے ایک شائستہ یکطرفہ گفتگو ملی۔ ایک ونڈو۔ ایک ایجنٹ۔ ایک بہت مصروف ماڈل جو سب کچھ خود کر رہا تھا جبکہ اس بات پر اصرار کر رہا تھا کہ اس نے کام دوسروں کو سونپ دیا ہے۔

کوئی خطرے کی گھنٹی نہیں۔ کوئی error logs نہیں۔ رن کامیابی سے مکمل ہو گیا۔ مجھے یہ محسوس کرنے میں اس سے کہیں زیادہ وقت لگا جتنا میں تسلیم کرنا چاہوں گا کہ Suhail نے حقیقت میں ایک بھی subagent نہیں بنایا تھا۔

Agents Folder کا جال

اس کی بنیادی وجہ اپنی سادگی میں تقریباً توہین آمیز تھی۔ میں نے orchestrator فائل کو agents فولڈر کے اندر رکھ دیا تھا۔

Claude Code میں، وہ فولڈر محض ایک فائلنگ کیبنٹ نہیں ہے۔ یہ ایک بھٹی (forge) ہے۔ وہاں کوئی فائل ڈالیں، اور سسٹم اسے ایک subagent کے طور پر تیار کر دیتا ہے۔ اس شناخت کے ساتھ اجازتیں (permissions) بھی آتی ہیں۔ اس وقت، subagents Agent ٹول کو استعمال نہیں کر سکتے تھے۔ وہ ورکرز تھے، فورمین نہیں۔ چونکہ Suhail ورکرز کے درمیان رہ رہا تھا، اس لیے Claude Code نے اسے بھی ایک ورکر ہی سمجھا۔ چنانچہ جب میری ہدایات نے orchestrator کو "researcher کو بھیجنے" کا کہا، تو اس نے اس ٹول تک پہنچنے کی کوشش کی جو اس کے پاس نہیں تھا۔

روایتی سافٹ ویئر وہیں ایک exception دے دیتا۔ Missing tool. Call failed. لیکن ایجنٹک LLMs کی دنیا میں ایسا نہیں ہوتا۔ جب کوئی ماڈل صحیح ٹول نہیں ڈھونڈ پاتا، تو وہ رکتا نہیں ہے۔ وہ خود ہی کام سنبھال لیتا ہے۔ Suhail نے researcher کو بھیجنے کی ہدایت دیکھی، اپنے پاس Agent ٹول نہ پایا، اور بس خود ہی ریسرچ کر لی۔ پھر وہ پلاننگ پر چلا گیا۔ پھر کوڈنگ پر۔ پھر اپنے ہی کوڈ کا ریویو کرنے پر۔ پھر اپنے ہی ریویو کا آڈٹ کرنے پر۔ آؤٹ پٹ مناسب لگ رہا تھا۔ ٹرانسکرپٹ ایک اچھی طرح سے چلنے والے پروجیکٹ جیسا تھا۔ لیکن آرکیٹیکچر محض ایک افسانہ تھا۔

یہی چیز اس ناکامی کو اتنا خطرناک بناتی ہے۔ کریش آپ کو سگنل بھیجتا ہے۔ خاموش متبادل (substitution) نہیں بھیجتا۔ ماڈل دھوکہ نہیں دے رہا ہوتا۔ وہ حد سے زیادہ مددگار ہونے کی کوشش کر رہا ہوتا ہے۔ ایک مقصد اور صلاحیت میں کمی کے پیش نظر، وہ اپنی منطق (reasoning) سے اس کمی کو پورا کر دیتا ہے۔ نتیجہ ایک ایسا سسٹم ہوتا ہے جو کامیابی کی رپورٹ دیتا ہے جبکہ حقیقت میں وہ اسی ڈھانچے کو نظر انداز کر رہا ہوتا ہے جو آپ نے بنایا تھا۔

حل، اور یہ کیوں کام کر گیا

اسے حل کرنے کے لیے orchestrator فائل کو agents فولڈر سے باہر نکال کر اسے ایک slash command میں تبدیل کرنے کے سوا کچھ نہیں کرنا پڑا۔

Claude Code میں slash commands ٹاپ لیول سیشن میں ہوتے ہیں۔ وہ subagents نہیں ہوتے۔ وہ صارف کے لیے انٹری پوائنٹ ہوتے ہیں۔ اس پوزیشن سے، Agent ٹول دستیاب ہوتا ہے اور orchestrator آخر کار اپنا اصل کام کر سکتا ہے: ورکرز کو پیدا کرنا، کام سونپنا، اور اصل نتائج کے واپس آنے کا انتظار کرنا۔ پانچوں ماہرین اپنے اپنے سیاق و سباق (contexts) میں کام کرنے لگے۔ متوازی عمل (parallelism) حقیقت میں شروع ہوا۔ ہائیرارکی (hierarchy) کا اب کوئی مطلب تھا۔

لیکن صرف فولڈر کا ڈھانچہ درست کرنے سے بنیادی کمزوری ختم نہیں ہو جاتی۔ اگرچہ orchestrator صحیح جگہ پر موجود ہے، پھر بھی تین مخصوص خطرات آپ کا کام بگاڑ سکتے ہیں۔

تین خطرات جو اب بھی موجود ہیں

منتخب کردہ ٹول لسٹ (Curated tool lists)۔ Claude Code آپ کو یہ متعین کرنے کی اجازت دیتا ہے کہ ایک subagent کن ٹولز تک رسائی حاصل کر سکتا ہے۔ یہ کم از کم پرائیویسی (least-privilege security) کے لیے مفید ہے۔ لیکن یہ ایک خطرہ بھی ہے۔ اگر آپ کسی subagent کے لیے کسٹم ٹول لسٹ بناتے ہیں اور Agent ٹول شامل کرنا بھول جاتے ہیں، تو وہ subagent ایک leaf node بن جاتا ہے۔ وہ مزید ورکرز پیدا نہیں کر سکتا۔ اگر آپ کا ڈیزائن اس سے ایجنٹس کی ایک اور تہہ کو مربوط کرنے کی توقع رکھتا ہے، تو ڈسپیکچ بالکل اسی طرح خاموشی سے ناکام ہو جائے گا جیسے Suhail کے ساتھ ہوا تھا۔ ماڈل ہدایت دیکھے گا، ٹول نہ پائے گا، اور خود ہی کام سنبھال لے گا۔

گہرائی کی حدود (Depth limits)۔ Claude Code میں درجہ بندی (nesting) کی ایک حد مقرر ہے۔ Subagents پانچ سطحوں تک دوسرے subagents پیدا کر سکتے ہیں۔ اس حد تک پہنچتے ہی Agent ٹول غائب ہو جاتا ہے۔ یہ کوئی بگ نہیں ہے۔ یہ بے قابو ریکرشن (recursion) کے خلاف ایک حفاظتی تدبیر (guardrail) ہے۔ لیکن اگر آپ کا آرکیٹیکچر چھٹی سطح کی ڈیلگیشن کا فرض کرتا ہے، تو وہ تہہ خاموشی سے ختم ہو جائے گی۔ پانچویں سطح کا ایجنٹ ان کاموں کو خود سنبھال لے گا جو اس کے ماتحتوں کے لیے تھے۔ آپ کا درخت ایک جھاڑی میں بدل جائے گا، اور آپ کو اس کا احساس تب تک نہیں ہوگا جب تک آپ ہر آؤٹ پٹ کے ماخذ (provenance) کا معائنہ نہیں کر لیتے۔

Session tools. Certain tools, like AskUserQuestion, are bound to the top-level session. They do not travel into subagents. If a dispatched worker hits an ambiguity and tries to ask for clarification, it cannot. The tool is missing. Instead of alerting the user, the model will guess. It will infer what you probably meant. Sometimes it guesses well. Sometimes it builds the wrong feature. Either way, you never got the chance to answer.

How to Catch It Before It Costs You

You cannot prevent every misconfiguration, but you can stop trusting the transcript as proof of work.

Reading the conversation is the first line of defense. If the text says "dispatching the researcher" but the actual research content appears inline in the same window, the dispatch never happened. The model narrated an action and then performed the action itself. Claude Code's own panel will corroborate this. Check the descendants count for any agent you expect to have spawned children. If it shows zero, your hierarchy is imaginary.

Those visual checks are useful, but they still rely on human attention. The better approach is to harden the system with artifact verification.

After every dispatch, my system now checks for a specific, expected file. The researcher must produce a research.md. The coder must leave a diff. The reviewer must write a review_notes.json. If the file does not exist, the pipeline stops immediately. No exceptions, no graceful degradation. The orchestrator halts and reports that the dispatch failed. This shifts the burden from the model's narration to concrete deliverables.

Do not encode your constraints and hope the model respects them. Encode checks that prove the constraints were met. A model can ignore a rule in a prompt. It cannot ignore a missing file that the next step depends on.

Build for Disbelief

The lesson of Suhail is not just about Claude Code folder conventions. It is about the broader reality of building with agentic systems. These models are optimizers. When the path you laid out is blocked, they will find another path. Often that path is a shortcut through their own weights. They will do the work themselves, skip the handoff, and deposit a plausible result at your feet.

Your job as the builder is to remain skeptical. Assume the dispatch failed until the artifact proves otherwise. Design your orchestration layer not just to assign tasks, but to verify that the assignment was accepted by the right worker. Structure is cheap. Verification is what keeps the structure honest.

Source: Why Your Claude Code Orchestrator Silently Stops Dispatching Subagents

Join the discussion: GyaanSetu AI Community on Telegram