Claude Architect Lab

Agent SDK Hooks: PostToolUse & Interception

Core

Apply Agent SDK hooks for tool call interception and data normalization · Difficulty 3/5

0%
hooksPostToolUseinterceptioncompliancenormalization
Prerequisites
Agentic Loop Lifecycle

Agent SDK hooks provide programmatic interception points in the agentic loop, enabling deterministic enforcement and data transformation without relying on prompt instructions.

PostToolUse Hooks (Result Transformation)

Intercept tool results BEFORE the model processes them. Use cases:

  • Data normalization: Convert Unix timestamps, ISO 8601 dates, and numeric status codes from different MCP tools into consistent human-readable formats
  • Result enrichment: Add computed fields or metadata
  • Filtering: Remove sensitive data before the model sees it

    • Tool Call Interception Hooks (Outgoing)

    Intercept outgoing tool calls BEFORE they execute. Use cases:

  • Compliance enforcement: Block refunds exceeding $500 and redirect to human escalation
  • Policy gates: Prevent actions that violate business rules
  • Audit logging: Record all tool calls for compliance

    • Hooks vs Prompt Instructions

    ApproachGuaranteeUse When

    |----------|-----------|----------|

    Prompt instructionsProbabilistic (non-zero failure rate)Soft preferences, style guidance
    HooksDeterministic (100% enforcement)Business rules, compliance, financial thresholds

    When a business rule MUST be followed every time (e.g., refund limits, identity verification), use hooks. Prompt instructions are appropriate for soft guidance where occasional deviation is acceptable.

    Key Takeaways

    • ✓PostToolUse hooks normalize tool output before the agent processes it
    • ✓Tool call interception hooks block policy-violating actions deterministically
    • ✓Use hooks (not prompts) when business rules require guaranteed compliance
    • ✓Hooks provide 100% enforcement; prompt instructions have a non-zero failure rate

    Glossary Terms

    PostToolUse Hook

    An Agent SDK lifecycle hook that intercepts tool results before the agent processes them. Can normalize, enrich, or transform results from multiple tools into a consistent format. Works with both custom and third-party MCP tools without modifying their source code.

    Related Concepts

    Multi-Step Workflow Enforcement

    Programmatic prerequisites are more reliable than prompt-based ordering