Programmatic Enforcement vs Prompt-Based Guidance

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.