Agent hooks: 7 tests before tools execute
AWS added deterministic hooks before and after invocations and tool calls. The value is not in accumulating callbacks, but in placing each policy at the last point where it can still prevent an action and proving it with adversarial tests.
- Published
- min read
- 6 min read
- Categoría
- AI Systems
On this page
6 chapters- 01The question is not whether the agent can act, but who authorizes it
- 02What each of the four boundaries can stop
- 03Separate capability, authorization, and evidence
- 04Hypothetical example: refunds with tiered approval
- 05The seven tests before expanding autonomy
- 06How to roll out without turning the hook into a blind spot

Chapter 02
What each of the four boundaries can stop
before_invocation validates the request before the agent starts, but its context contains the current call's messages before session state is restored. It fits identity, tenant, purpose, budget, or consent checks for the requested operation. before_tool_call receives the proposed tool name, type, identifier, and input; it is the natural gate for amount, destination, scope, data classification, and idempotency before execution. When it denies, the tool is skipped and the loop may continue to explain or escalate.
after_tool_call observes a result that already exists. It can stop later inference and prevent the agent from chaining another action, but it does not undo the tool's effect. after_invocation receives the stop reason and token usage after the invocation completes; it serves accounting, alerts, and review, not authorization. The design rule is simple: place a condition at the earliest boundary with sufficient evidence, and never use a later hook as a substitute for a preventive control.
| Boundary | Useful decision | Limit |
|---|---|---|
| Before invocation | Accept purpose, actor, and budget | Does not see the tool call yet |
| Before tool | Authorize parameters and effect | Must answer within the timeout |
| After tool | Validate the result before continuing | The effect already occurred |
| After invocation | Audit completion and usage | Cannot retract output |
Chapter 03
Separate capability, authorization, and evidence
A hook does not replace least privilege. AgentCore can pin allowedTools; when that field is omitted or uses a wildcard, the managed set may gain capabilities as the harness evolves. A product with a fixed boundary should enumerate concrete tools and separate read, write, and edit. Next, the execution identity limits resources; finally, the hook decides whether an allowed call is also authorized for this actor, object, time, and purpose. These are three different layers: technical capability, infrastructure permission, and business policy.
Evidence needs its own contract as well. Stream hookEvent records confirm which hook fired and, for Lambda, which decision was applied. By contrast, an SNS or EventBridge event only confirms that dispatch was scheduled, not that the consumer received it. Preserve hookEventId, sessionId, toolUseId, policy version, decision, reason, and a reference to the effect in a durable system of record. Avoid copying full sensitive payloads when hashes, identifiers, and minimal fields are enough to reconstruct the decision.
Chapter 04
Hypothetical example: refunds with tiered approval
Imagine a support agent that reads orders and proposes refunds. This example is hypothetical and does not represent a Wasyra client or result. before_invocation checks that the operator belongs to the tenant and that the user asked to resolve that order. The runtime identity can only read that tenant's orders and call a constrained refund function. before_tool_call validates currency, amount, order, reason, return window, beneficiary, and idempotency key. Up to a low threshold it allows; above it, the hook returns deny and creates a human approval request in a separate system.
The tool returns a providerTransactionId. after_tool_call verifies that the result matches the order and records an uncertain state on timeout instead of retrying blindly. The agent can explain that the case was escalated, but it cannot turn a denial into an alternative tool with the same effect. To enforce that, all equivalent routes share an effect taxonomy and the same policy. Tool hooks also apply to subagents, reducing delegation bypass; you must still test aliases, inline functions, and gateways that materialize the same effect.
Chapter 05
The seven tests before expanding autonomy
Test 1, blocked effect: a before-tool denial must produce zero provider calls. Test 2, equivalence: aliases, subagents, and inline functions cannot bypass the same policy. Test 3, closed failure: Lambda timeout, exception, and invalid response must adopt the intended failureMode; for irreversible actions, deny is usually the defensible value. Test 4, truncated context: hook payloads are limited to 64 KiB and mark truncated fields; if policy needs missing data, it must deny or consult a trusted record, never assume.
Test 5, concurrency: when multiple Lambda hooks share an event, they run concurrently and any deny applies; verify that the visible reason and policy dependencies remain deterministic. Test 6, retry and idempotency: a dropped connection cannot duplicate the effect, and an uncertain result must reconcile before re-execution. Test 7, complete evidence: correlate request, decision, tool call, result, and final effect; also alert when the asynchronous channel does not deliver. Exercise allow and deny paths, exact thresholds, malformed data, cross-tenant access, replay, and dependency degradation.
Chapter 06
How to roll out without turning the hook into a blind spot
Start in shadow mode: compute the decision and record divergences without blocking, but only for reversible or simulated operations. Then activate deny for one narrow high-risk class and measure p50/p95/p99 latency, timeouts, denial reasons, human appeals, false positives, and effects without complete evidence. Version configuration and function as one unit. Updating hooks replaces the supplied list, so test the full document and detect accidental removals before promotion.
The limitations still matter. A synchronous hook adds latency and availability dependencies to the critical path. after_tool_call does not reverse the external world. A client-supplied inline result proves that the harness processed it, not that the action truly happened; authenticate the caller and validate against the system of record. Do not confuse deny with a complete strategy either: you still need consent, separation of duties, rate limits, reconciliation, and rollback where possible. Move forward when all seven tests pass in a representative environment and every denial has an understandable recovery path.
If you are designing an agent with real tools, first turn every action into an effect contract: who may request it, which fields are required, which gate authorizes it, how it fails, how it reconciles, and what evidence proves the outcome. Wasyra can help you design and validate that operational slice without conflating it with the separate Agents product at agents.wasyra.com.
Written by
Wasyra Lab
AI systems and operations architecture
Wasyra Lab publishes practical frameworks for designing AI agents, automations, and operating flows that survive production.
Series
AI systems that actually reach production
A series on agents, copilots, and guardrails for bringing AI into real work without breaking trust or operations.
Posts in this seriesMore from this author
More from this author
AI Systems
Scientific post-training: 7 evidence gates
Nemotron for Science opens scientific post-training. These seven gates prevent proxy optimization, test leakage, and false improvements.
ArticleAI Systems
Agentic RL: how to read MLPerf Training 6.1
MLPerf now measures agent post-training. Learn how to read time to quality, workload limits, and useful infrastructure decision signals.
ArticleKeep reading
Keep reading
AI Systems
Scientific post-training: 7 evidence gates
Nemotron for Science opens scientific post-training. These seven gates prevent proxy optimization, test leakage, and false improvements.
ArticleAI Systems
Agentic RL: how to read MLPerf Training 6.1
MLPerf now measures agent post-training. Learn how to read time to quality, workload limits, and useful infrastructure decision signals.
ArticleAI Systems
Portable agent skills: production contracts
A portable skill does not transfer permissions or guarantees. Seven contracts separate instructions, tools, approval, testing, and rollback.
Article