Agent Hooks: Contracts for Blocking, Response Changes, and Notifications
TECH INSIGHT / EXPLAINED
Hooks connect pre-tool checks, post-tool notifications, and response transformations outside the agent core. Their behavior depends less on event names than on whether the pipeline waits and what happens on failure.
Separate blocking, transformation, and observation
A pre_tool_use authorization decision must finish before execution. A pre_response hook that adds required text or removes secrets must finish before delivery. Optional statistics and post-execution notifications can use a separate queue. Do not classify every response hook as asynchronous.
Errors, timeouts, and unknown decisions in mandatory security checks should deny the action. Optional analytics may fail without stopping the request, but declare that policy at registration and prevent extensions from weakening required checks.
A shell regex is not an isolation boundary
Blocking a few destructive command patterns does not make arbitrary command execution safe. Prefer structured tools with explicit executable, argument, and path allowlists. If a command hook is necessary, pass data through stdin or separate arguments and run with minimal process privileges.
An embedded JavaScript engine's capabilities depend on exposed host functions, files, and networking. Creating a timeout context alone may not stop an infinite loop. Wire runtime interruption and CPU, memory, and output limits into execution, then test them.
Validate again after mutation
Even trusted hooks with limited mutation rights must send the final arguments through schema, authorization, and scope validation. Fix hook ordering and conflict rules; log hook version, event ID, and changed field names. A tenant hook can operate only inside its authorized scope.
Notifications are external side effects
Asynchronous delivery needs persisted events, retries, deduplication identifiers, and terminal failure status. An event ID helps, but without destination-side idempotency you cannot guarantee exactly-once delivery after a connection fails just after acceptance. Distinguish “tool invoked” from “order actually filled.”
Audit logs still carry privacy implications
Hashing inputs obscures raw text but does not guarantee anonymity: guesses and equality linkage can reveal information. Minimize fields, redact sensitive values, and set retention and read permissions. A dedup_key column needs a uniqueness constraint and atomic insertion to enforce deduplication.
Code can require a notice in the final response before sending. Hook errors, delivery failures, and bypass paths still exist, so detecting failure and recording delivery status is more defensible than claiming universal success.
Maintaining permissions and result review across agents
References
Content and examples reviewed: 2026-09-29
댓글
댓글 쓰기