PostToolUse وخطافات الاستدعاءات الصادرة
اعترض نتائج الأدوات واحظر الإجراءات المخالفة للسياسات
PostToolUse وخطافات الاستدعاءات الصادرة درس مجاني في Claude Architect على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Claude Architect، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Claude Architect 4 دروس في المجموع.
بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.
Why Hooks Exist
Prompts steer the model, but they are probabilistic — roughly 90% reliable. For most behavior that is fine. But some actions must never slip through: issuing a large refund, deleting production data, sending money.
Hooks give you 100% deterministic enforcement. They are code that runs around tool execution, outside the model's discretion. Use hooks when a failure has financial, legal, or safety consequences.
Two Hook Points to Know
This lesson covers two enforcement points:
- PostToolUse — fires after a tool runs and intercepts the result before the model sees it. You can trim, validate, redact, or reshape tool output.
- Outgoing-call hooks — block a policy-violating action before it leaves your system (e.g. a refund above a threshold).
Together they bracket the dangerous part of the agentic loop: the moment a tool result enters the conversation, and the moment a side effect would escape it.
Where Hooks Sit in the Loop
Recall the agentic loop: send request, inspect stop_reason, and when it is tool_use, run the tool and append the result to history, then repeat until end_turn.
A PostToolUse hook wraps that 'run the tool' step. The model requests a tool call; your code executes it; before appending the result to the message history, the hook inspects and may modify it.
def run_tool_with_hook(tool_name, tool_input, tool_use_id):
raw_result = execute_tool(tool_name, tool_input)
# PostToolUse: inspect/transform BEFORE the model sees it
safe_result = post_tool_use_hook(tool_name, raw_result)
return {
"type": "tool_result",
"tool_use_id": tool_use_id,
"content": safe_result,
}PostToolUse: Trim Verbose Output
A common, practical PostToolUse job is trimming tool output to the relevant fields. Raw API responses are often huge, and bloated context triggers the lost-in-the-middle problem — models attend to the start and end of context more than the middle.
The hook reshapes the result deterministically, so the model only ever sees the fields that matter.
def post_tool_use_hook(tool_name, raw_result):
if tool_name == "lookup_order":
# Keep only fields the model needs; drop the rest
return {
"order_id": raw_result["id"],
"status": raw_result["status"],
"total": raw_result["total"],
}
return raw_resultPostToolUse: Structured Errors, Not Generic Ones
PostToolUse is also where you normalize errors. A generic status like "Operation failed" blocks recovery — the model cannot tell a transient fault from a permission problem.
Reshape failures into structured errors so the model can route intelligently: a flag, a category, retryability, and context.
def post_tool_use_hook(tool_name, raw_result):
if raw_result.get("error"):
return {
"isError": True,
"errorCategory": "transient", # transient/validation/business/permission
"isRetryable": True,
"message": raw_result["error"],
"attempted_query": raw_result.get("query"),
"partial_results": raw_result.get("partial", []),
}
return raw_resultDistinguish Failure from Empty
One subtle rule PostToolUse helps enforce: an access failure is not the same as a valid empty result.
- A failed query (timeout, auth) is an error the model may retry.
- An empty result (zero matching orders) is a legitimate answer — retrying changes nothing.
Encode the difference so the model never burns iterations retrying a query that simply has no matches.
def post_tool_use_hook(tool_name, raw_result):
if tool_name == "lookup_order":
if raw_result.get("connection_error"):
return {"isError": True, "errorCategory": "transient",
"isRetryable": True}
# Empty is a VALID answer, not an error
return {"orders": raw_result.get("orders", []),
"isError": False}
return raw_resultOutgoing-Call Hooks: The Hard Stop
Now the headline use case. The exam's Customer Support scenario has a tool process_refund. Policy: refunds over $500 require a human.
You could write that rule in the prompt — but a prompt is ~90% reliable, and a single missed refund is a real financial loss. So you wrap the outgoing call in a hook that blocks deterministically when the threshold is exceeded. The model's judgment never gets a vote here.
REFUND_LIMIT = 500
def outgoing_call_hook(tool_name, tool_input):
if tool_name == "process_refund" and tool_input["amount"] > REFUND_LIMIT:
# Block the side effect; hand control back to the model
return {
"blocked": True,
"reason": "Refund over $500 requires human approval.",
"next_action": "escalate_to_human",
}
return execute_tool(tool_name, tool_input)Programmatic Preconditions
Outgoing-call hooks also enforce preconditions — ordering guarantees a prompt cannot reliably provide. Example: never process a refund until get_customer has returned a verified identity.
The hook checks a fact in your own state, not the model's claim that it 'already verified'. That is the difference between a deterministic guarantee and a hopeful instruction.
def outgoing_call_hook(tool_name, tool_input, session_state):
if tool_name == "process_refund" and not session_state.get("verified_customer_id"):
return {
"blocked": True,
"reason": "Identity not verified. Call get_customer first.",
}
return execute_tool(tool_name, tool_input)Feed the Block Back to the Model
Blocking is only half the job. A hook that silently swallows the action leaves the model confused and the loop stalled — that is silent suppression, an anti-pattern.
Instead, return the block as a tool result the model can read and act on. A good block message names the reason and the correct next step (here, escalate_to_human), so the agent recovers cleanly inside the same loop.
def handle_tool_call(tool_name, tool_input, tool_use_id, state):
outcome = outgoing_call_hook(tool_name, tool_input, state)
if isinstance(outcome, dict) and outcome.get("blocked"):
return {"type": "tool_result", "tool_use_id": tool_use_id,
"is_error": True, "content": outcome["reason"]}
return {"type": "tool_result", "tool_use_id": tool_use_id,
"content": outcome}Hooks vs Iteration Caps
Do not confuse enforcement hooks with the loop's safety net. An iteration cap stops a runaway loop, but it is a backstop — never the primary control mechanism, and never a substitute for policy enforcement.
Hooks are the opposite: a precise, intentional guarantee on a specific action. The model still drives decisions; hooks reserve hard code only for the guarantees that genuinely matter.
When to Reach for a Hook
Decision rule for the exam and for production:
- Use a hook when failure is financial, legal, or safety-critical, or when you need a deterministic precondition or threshold (refund > $500, verified ID before payout).
- Use a prompt for soft guidance, tone, and the ~90% of behavior where an occasional miss is acceptable.
Hooks = deterministic. Prompts = probabilistic. Match the tool to the cost of being wrong.
Quick Check
A support agent has a process_refund tool. Company policy: refunds above $500 must be approved by a human. Most refunds are small and automated. What is the architect-grade way to enforce this?
Recap
Key takeaways:
- PostToolUse intercepts tool results before the model sees them — trim verbose output, normalize generic failures into structured errors, and distinguish access failure from a valid empty result.
- Outgoing-call hooks block policy-violating actions (refund > $500) and enforce preconditions (verified ID before payout).
- Hooks = 100% deterministic; prompts = ~90% probabilistic. Use hooks when failure is financial, legal, or safety-critical.
- Always feed a block back as a structured result — never suppress silently. Iteration caps are a safety net, not enforcement.
الأسئلة الشائعة
هل درس «PostToolUse وخطافات الاستدعاءات الصادرة» مجاني؟
نعم — نص درس «PostToolUse وخطافات الاستدعاءات الصادرة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Claude Architect، انتقل إلى CoddyKit PRO. تتضمن دورة Claude Architect 4 دروس في المجموع.
ماذا ستتعلم في «PostToolUse وخطافات الاستدعاءات الصادرة»؟
اعترض نتائج الأدوات واحظر الإجراءات المخالفة للسياسات تتمرن على Claude Architect مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ Claude Architect؟
لا تُشترط خبرة سابقة. Claude Architect على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.
كم من الوقت يستغرق درس «PostToolUse وخطافات الاستدعاءات الصادرة»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس Claude Architect هذا؟
نعم. كل درس في Claude Architect يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- PostToolUse وخطافات الاستدعاءات الصادرة
- الإنفاذ الحتمي مقابل المطالبات
- الشروط المسبقة البرمجية
- بروتوكولات التسليم المنظّمة