How it works
A tool-use hook sits on the invocation path between an agent loop and a tool. It runs at a defined lifecycle point, usually immediately before the tool executes or immediately after it returns. The hook receives context such as the tool name, proposed arguments, run identity, current state, permission data, and correlation identifiers. A post-action hook may also receive the result, error, duration, or completion status.
A typical control path is:
- The model or workflow proposes a tool call.
- A pre-action hook inspects the call against deterministic rules or an approval policy.
- The hook returns an explicit decision: allow, deny, require approval, or apply a documented transformation.
- If allowed, the harness invokes the tool.
- A post-action hook records the outcome, validates returned data, updates authoritative state, or triggers containment and recovery logic.
The hook should have a narrow contract. It should not quietly become another agent loop or an unbounded policy engine. Its inputs, possible decisions, ordering, timeout behavior, and failure semantics need to be explicit. If multiple hooks run, the harness also needs a deterministic rule for precedence and short-circuiting. Otherwise two individually reasonable controls can produce an invocation path that nobody can explain.
Why it matters in an agent harness
Tool calls are where generated intent becomes an external effect. A model can reason incorrectly without changing the world. A tool call can send a message, modify a record, execute code, or initiate an operation that cannot be cleanly reversed. A tool-use hook gives the harness a control point at that transition.
Pre-action hooks are useful for enforcing constraints that should not depend on the model’s judgment. They can reject arguments outside an allowed scope, compare a requested operation with delegated authority, require approval for a high-impact action, or enforce a tool budget. This reduces the chance that prompt injection, stale context, or an over-broad plan turns into an authorized but inappropriate action.
Post-action hooks close a different gap. A successful transport response does not necessarily mean the intended state change occurred, and a timeout does not prove that it did not. The hook can capture the raw outcome, attach it to an execution trace, distinguish a confirmed failure from an unknown outcome, and prevent the loop from blindly retrying a non-idempotent operation.
Hooks also improve observability because they see structured invocation context rather than reconstructing events from prose logs. They can preserve the proposal, policy decision, effective arguments, result status, and correlation identifier as separate facts. That record supports incident review, trajectory evaluation, and execution replay without treating the model transcript as the sole source of truth.
A hook is not a replacement for authorization inside the tool or service. The receiving system must still enforce its own permission boundary. Harness-side checks constrain agent behavior and improve operator control; service-side checks protect the underlying resource. Production systems usually need both because either layer can be misconfigured, bypassed, or supplied with incomplete context.
Failure behavior is part of the control design. If a permission hook times out and the harness proceeds, the hook is decorative. If a telemetry-only hook fails and blocks every action, observability has become an availability dependency. Each hook therefore needs a declared criticality and a visible failure result. Fail-open and fail-closed behavior should be chosen deliberately for that specific responsibility.
Tool-use hook vs middleware
Both mechanisms intercept a request path, but they operate at different semantic layers. The distinction affects which context is available and where policy belongs.
| Axis | Tool-use hook | Middleware |
|---|---|---|
| Primary object | An agent’s proposed or completed tool action | A transport or application request |
| Typical context | Run state, tool identity, delegated authority, arguments, agent decision | Headers, route, session, request body, response |
| Best suited for | Approval, tool policy, invocation tracing, agent-specific containment | Authentication, transport logging, rate limiting, protocol concerns |
| Lifecycle meaning | Before or after an agent action | Before or after request handling |
Middleware can enforce broad service rules without knowing why an agent made a call. A tool-use hook can reason over harness state but should not duplicate transport security. I keep the layers separate and pass only the identifiers needed to correlate their records.
The Rifty take
We treat tool-use hooks as explicit control boundaries, not convenient callback slots. We optimize for small, deterministic handlers with inspectable decisions, and we accept some invocation overhead in exchange for clearer authority, containment, and recovery. A hook that changes or suppresses an action must leave evidence that it did so.
Implementation checks
- Define whether the hook runs before invocation, after invocation, or on both paths.
- Specify its input schema and version it when fields or meanings change.
- Make allow, deny, approval, and transformation decisions explicit values.
- Record the original arguments separately from any transformed arguments.
- Declare hook ordering, short-circuit rules, timeouts, and retry behavior.
- Fail closed for missing authorization decisions; do not silently default to approval.
- Treat unknown tool outcomes separately from confirmed failures before retrying.
- Give each action a correlation identifier that survives hooks, tool execution, and recovery.
- Keep credentials out of hook records unless the hook strictly requires them.
- Test denial, timeout, duplicate invocation, partial completion, and hook failure paths.
Frequently asked questions
Should a tool-use hook be allowed to modify tool arguments?
Yes, but only through an explicit, recorded transformation contract. Preserve the original arguments, validate the transformed call again, and show which hook made the change. Silent mutation damages auditability and can invalidate the model’s assumptions about what action was actually executed.
What should happen when a pre-action hook fails?
A control-critical pre-action hook should normally block the invocation and surface an operational error. Proceeding without a required permission or policy decision creates a silent fail-open path. Noncritical hooks need separately declared behavior so a telemetry failure is not mistaken for authorization.
Can tool-use hooks replace approval gates?
No. A hook can evaluate an approval policy and route a call into an approval flow, but it is only one enforcement point. The approval decision, operator identity, expiry, authorized scope, and eventual invocation should remain explicit state that the harness can verify and audit.
How should post-action hooks handle tool timeouts?
They should record an unknown outcome unless the tool contract proves that no effect occurred. The harness can then reconcile state, query an idempotency key, or request operator intervention. Automatically treating every timeout as failure can cause duplicate external effects when the action actually completed.
What makes a tool-use hook observable enough for production?
Record the run and call identifiers, lifecycle point, hook version, policy inputs, decision, effective arguments, result status, and timing. Sensitive fields should be redacted deliberately. Operators must be able to reconstruct why an action ran, changed, stopped, or entered recovery without reading model prose.