Agents & Tool Use
Programmatic Enforcement vs Prompt-Based Guidance
When to use hooks and programmatic prerequisites for guaranteed compliance versus system prompt instructions for probabilistic guidance.
intermediate · 6 min read
One of the most critical architectural decisions in agent design is choosing between deterministic enforcement and probabilistic guidance.
Programmatic Enforcement
Hooks and prerequisite gates provide 100% compliance. A programmatic prerequisite that blocks process_refund until get_customer has returned a verified customer ID will never fail. The tool literally cannot execute until the prerequisite is met.
Use programmatic enforcement when:
- Identity verification is required before financial operations
- Business rules have legal or financial consequences
- Tool ordering must be guaranteed, not hoped for
- Non-compliance could result in incorrect refunds, data exposure, or policy violations
Prompt-Based Guidance
System prompt instructions and few-shot examples provide probabilistic compliance. They work most of the time but have a non-zero failure rate. In production data, you might see 12% of cases where the agent skips a step it was instructed to perform.
Use prompt-based guidance when:
- The preference is stylistic (output formatting, tone)
- The consequence of non-compliance is minor
- You want to influence behavior without hard constraints
Agent SDK Hooks
The Agent SDK provides two key hook patterns:
PostToolUse hooks transform tool results before the model processes them. Use these to normalize heterogeneous data formats (Unix timestamps to ISO 8601, numeric status codes to human-readable labels).
Tool call interception hooks enforce compliance rules before execution. They can block operations above a threshold (refunds over $500) and redirect to alternative workflows (human escalation).
The rule: when business logic requires guaranteed compliance, use hooks. When you're guiding preferences, use prompts.