Lesson 5 of 6 in Agentic Architecture & Orchestration

1.5 · Guardrails, hooks, and safe termination

Autonomous systems fail in autonomous ways. This lesson covers the three defence layers every production agent needs: circuit-breaker caps, deterministic hook-based gates, and explicit escalation paths. The exam consistently tests whether you know that prompt-level guardrails are suggestions, not enforcement — and that hooks are the correct mechanism for critical business rules.

The three safety caps

Every production agent needs three circuit breakers: max iterations, max cost/tokens, and wall-clock timeout. They exist to catch bugs, not to control flow. Log when they fire because a firing cap indicates a design problem upstream.

Hooks as deterministic gates

In Claude Code, hooks fire on lifecycle events like PreToolUse, PostToolUse, and Stop. Each hook is an external script whose exit code determines the action. Exit 0 allows; exit 2 blocks the action and surfaces stderr back to Claude as feedback.

#!/usr/bin/env bash
# .claude/hooks/pre-tool-use.sh
# Block writes to protected paths

# Hook receives JSON on stdin
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool')
path=$(echo "$input" | jq -r '.args.path // ""')

if [[ "$tool_name" == "edit_file" || "$tool_name" == "write_file" ]]; then
  if [[ "$path" == /infra/secrets/* || "$path" == *.env ]]; then
    echo "BLOCKED: writes to $path are protected" >&2
    exit 2
  fi
fi

exit 0  # allow

Escalate before you fail

Design explicit escalation paths: low confidence, repeated tool failure, or a request outside the agent's tools should hand off to a human or a more capable model — not loop until the iteration cap kills the run.

Good to know — 'Retry harder' is not an escalation. Real escalation changes who or what is handling the task.

The confidence-calibrated stop

For high-stakes outputs (refunds, code changes, medical suggestions), have the agent report its confidence alongside the output. Low confidence routes to human review; high confidence proceeds. This is different from letting the model self-critique — confidence is calibration, not review.

Anti-patterns to recognize

Parsing text for termination. Iteration cap as primary stop. Universal tool access for every subagent. Silent failures. Retry loops without state change. All show up as wrong-answer options on the exam.

Good to know — 'Add retry' as an answer is a red flag when the root cause is unaddressed.

Takeaways

  • Caps are circuit breakers; log when they fire
  • Hooks use exit codes (0 allow, 2 block) for deterministic safety nets
  • Build explicit escalation paths — don't let the loop simply exhaust
  • Ship confidence signals for high-stakes decisions

Exam traps

Enforcing critical business rules via prompt instructions instead of hooks
Prompt instructions like 'never refund more than $500' are followed most of the time but not every time. For financial, security, or compliance rules, use PreToolUse hooks that programmatically block the operation.
Treating iteration caps as the primary control mechanism
Iteration caps are safety nets to catch bugs, not primary control. If the loop terminates via the cap in normal operation, the design is wrong. Use stop_reason for control.
Retrying repeatedly instead of escalating on persistent failure
When the same tool fails 5+ times, the answer is not 'retry more.' It is 'escalate to a human or a stronger model.' Retry loops without state change waste tokens and delay real resolution.

Practice scenario

A customer support agent has a tool 'issue_refund' that the model should never call for amounts over $500 without human approval. The team is deciding how to enforce this. Which approach is correct?

← PreviousNext →