An agent can describe a policy accurately and still initiate an unauthorized refund. Identity checks, amount limits and state transitions therefore cannot exist only as instructions to the model. The Claude Agent SDK can expose hooks around proposed tool use, but a hook should check trusted application state rather than assume that fluent reasoning proves permission. In the agent architectures studied for Anthropic CCA-F, all three boundaries must work: Claude may propose an action, the hook may reject it, and the refund service independently checks account identity, eligibility and idempotency before money moves.
Choose the right execution boundary
A conversational instruction influences what Claude decides to do. A tool interceptor observes what the system is about to do, or what a tool has just returned. These are different control points. A pre-execution check can evaluate a proposed operation against verified application state before side effects occur; a post-execution hook can normalize the result or record an outcome. The difference is crucial when a tool both reads and writes. Redacting output after a payment has been submitted is too late to protect the payment. Conversely, an approved call does not guarantee that the vendor’s response has the expected shape.
Map execution as input acceptance, tool proposal, authorization, actual execution and result ingestion. Assign each policy to the earliest boundary that can enforce it reliably. A tool that generates a customer summary may need output redaction, while a tool that issues credit needs authorization before execution. This is a practical extension of Claude agent architecture: autonomy operates inside a boundary that code can actually enforce. A hook should make that boundary explicit. It should not become an indiscriminate collection of unrelated application logic.
Protect consequential actions before they run
Suppose Claude investigates a duplicate-charge complaint and proposes a refund, including a purchase identifier and amount. Before execution the application needs proof of account ownership, a refund limit, settled payment status and an unused idempotency key. These are database facts and business-policy predicates, not prose judgments. A pre-tool check can block the call and return a structured reason when a condition is missing. It must not ask Claude to manufacture a verification record or treat the sentence “customer is verified” as authoritative evidence.
Test with ordinary requests, ambiguous identities, an approval that expires mid-session and a malicious attachment that falsely asserts higher authorization. The untrusted text might influence Claude’s proposed call, but the authorization gate should reject the forbidden action. Where a backend payment service is available, keep enforcement there too. A hook reduces dangerous calls; backend validation covers other clients and bypass routes. It is also essential to distinguish a denied action from an action that failed after submission, because the latter may already have financial consequences.
Normalize tool results without fabricating certainty
Consider three shipping APIs. One returns an ISO timestamp, another returns a date without a time zone, and the third says the parcel is “arriving today.” Claude may interpret all three as equivalent, but they are not. A post-tool handler can convert documented values into a canonical schema, attach source identifiers and observation times, and mark unresolved fields explicitly. If the source omitted a time zone, the handler must not silently append UTC or guess the customer’s local zone.
Normalization is not evidence laundering. Preserve the raw response or a recoverable source reference when auditing requires it, and record which transformations were mechanical. Mapping an officially documented status code to a canonical enumeration is deterministic; inferring a promise from free-form email is not. Downstream Claude reasoning should be able to distinguish observed facts, justified conversions and open questions. Otherwise a tidy schema can make a low-confidence answer look more trustworthy than its evidence allows.
Keep hook responsibilities small
A hook that handles authorization, formatting, logging, routing, retries and business decisions is difficult to test. Keep the enforcement point distinct from which tools a worker is allowed to select: the catalog limits available actions, while a hook or backend rule evaluates the proposed call. The agent execution loop must then propagate an authorization denial as a real state, not a request for Claude to choose a more persuasive wording. Prefer narrow stages with explicit contracts. Permission evaluation returns allow or deny and a reason code. Result normalization returns declared fields or a recognizable validation error. Audit recording stores operation identifiers, timing and decisions without unnecessarily copying sensitive source material. Each stage has its own failure policy. For a privileged operation, inability to check permissions ordinarily means do not proceed.
Imagine an authorization service is unavailable. A weak system interprets its timeout as an allow decision so the agent can continue. A safer policy pauses consequential actions, records the proposed operation for review and may permit unrelated read-only investigation. The correct tradeoff is a product decision made before an incident, not a choice improvised by the model. The assistant should receive a specific limitation and safe alternatives rather than internal stack traces or an invitation to retry until the service responds.
Test enforcement rather than wording
Unit tests should invoke hook handlers with controlled tool names, parameters and application states. For a financial action, cover permitted refunds, excess amounts, missing identity, stale authorization, mismatched case IDs, duplicate operation keys and unavailable policy data. Verify both the returned verdict and that the underlying privileged operation was actually prevented. A simulated denial message appearing in Claude’s conversation is not enough if another route still executes the write. Unexpected parameters and new aliases must not make an otherwise protected tool invisible to validation.
Integration tests should check execution order. A pre-call hook is effective only if the relevant action passes through it before the side effect. A post-call transformation must run before the model consumes the normalized result when the application depends on that form. Follow a complete case with a deliberate exception, then inspect attempted action, evaluated rule, authorization decision, execution and final outcome. If reviewers cannot reconstruct the sequence, the controls may appear effective only because the simple test avoided a real failure path.
Account for delegated agents and uninstrumented paths
Hooks are useful controls, not universal guarantees of correctness. They cannot prove that a recommendation is wise or that an external service is telling the truth. They also do not automatically cover tools executed outside the instrumented runtime. Inventory direct tool calls, delegated workers, MCP connections and any application endpoints that can perform the same privileged operation. A specialist agent should not become the easy route around a rule that blocks the coordinator. Establish the same backend authorization boundary across all those paths.
A thorough review examines what the agent can reach, not just what appears in a configuration file. A previously harmless lookup tool may gain a new update operation in a later release. That can create a privilege expansion without any change to the model’s instructions. Compare the tool’s actual behavior, method permissions and advertised descriptions, and re-run denial cases across the complete action inventory. The success criterion is that forbidden external state remains unchanged, not merely that one familiar hook logs a warning.
Respect differences between SDK and Claude Code hooks
Agent SDK hooks, Claude Code hooks and managed-agent event callbacks are related but not interchangeable interfaces. Their event names, installation mechanisms, timeouts and return contracts may differ by runtime and version. A production design should name the exact implementation and the events it uses, then test that configuration on the installed release. Copying a snippet from another product surface can silently omit enforcement because it runs at a different boundary or produces a response that the current runtime does not understand.
Keep a versioned contract for protected tool names, matcher rules and approval responses. A refactor that renames the refund tool can leave a pre-call matcher targeting the old name. CI should detect the missing coverage before deployment, including a deny test that exercises the new name. Such checks turn a one-off hook into a maintained security control. The certification’s durable lesson is architectural: protect the action at a deterministic boundary, rather than memorizing a particular callback signature as though it will never change.
Follow a refund case to closure
A customer provides a transaction number but cannot verify account ownership. Claude proposes a refund because the duplicate charge appears obvious. A pre-action gate denies the request with an identity_missing state; the assistant explains the permitted verification step without exposing internal data. After verification succeeds, Claude proposes the operation again. The gate checks amount limits, settlement state and a fresh idempotency key. The backend independently confirms permission, commits the refund and returns an operation reference that a post-call handler normalizes for the conversation and audit record.
If the refund acknowledgment is ambiguous, the system must investigate authoritative transaction status before retrying. The principles in recovering from tool errors are especially important when side effects may already have happened. Claude handles language and investigation; the hook enforces prerequisites; the service executes a privileged action; the record proves the observed outcome. The architect chooses a layer that makes forbidden states unreachable while giving the model enough accurate information to continue the permitted parts of the work.