#22068: Add tool:before/tool:after internal hook events
docs
agents
size: M
Cluster:
Plugin Hook Enhancements
## Summary
- add new internal hook event type `tool` with typed contexts for `tool:before` and `tool:after`
- emit `tool:before` and `tool:after` from the central tool execution wrapper (`wrapToolWithBeforeToolCallHook`)
- support pre-execution abort via `event.context.abort()` in `tool:before`
- include success/failure metadata (`durationMs`, `result`, `error`) in `tool:after`
- add tests for new type guards and end-to-end tool hook emission/abort behavior
- document tool hook events in automation hooks docs
## Issue Intent Check (#7597)
- real-time interception before execution: ✅ (`tool:before`)
- real-time execution outcome hooks: ✅ (`tool:after`)
- guardrail blocking path: ✅ (`abort()` + hook message propagated as error)
- audit payload for monitoring/compliance: ✅ (tool, toolCallId, arguments, success, durationMs, result/error)
## Validation
- `corepack pnpm exec vitest run src/hooks/internal-hooks.test.ts`
- `corepack pnpm exec vitest run --config vitest.e2e.config.ts src/agents/pi-tools.before-tool-call.e2e.test.ts`
- `corepack pnpm lint`
- `corepack pnpm test:fast`
## Notes
- Per-tool aliases like `tool:exec:before` were not added. Existing hook filtering can key off `event.context.tool === "exec"`.
Closes #7597
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR adds comprehensive `tool:before` and `tool:after` internal hook events to enable real-time tool execution monitoring and guardrails. The implementation correctly emits hooks from the central tool wrapper (`wrapToolWithBeforeToolCallHook`), supports pre-execution abort via the `abort()` callback, and includes success/failure metadata in the `tool:after` event. The changes are well-tested with both unit tests for type guards and e2e tests for the full hook emission flow.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The implementation is well-structured with comprehensive test coverage (unit tests for type guards + e2e tests for hook emission and abort behavior). The changes follow existing patterns in the codebase, maintain backward compatibility, and include clear documentation. All hook events are properly typed with TypeScript type guards, and the abort mechanism correctly prevents execution while still emitting `tool:after` events for audit trails.
- No files require special attention
<sub>Last reviewed commit: 456e637</sub>
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#10678: feat(hooks): wire after_tool_call hook into tool execution pipeline
by yassinebkr · 2026-02-06
83.4%
#16028: feat/before-tool-result
by ambushalgorithm · 2026-02-14
81.8%
#20580: feat(hooks): bridge after_tool_call to internal hook handler system
by CryptoKrad · 2026-02-19
80.7%
#11071: Plugins: add tool_result_received hook for output interception
by ThomasLWang · 2026-02-07
79.9%
#17667: feat: tool-hooks extension — run shell commands on tool calls
by FaradayHunt · 2026-02-16
79.5%
#18889: feat(hooks): add agent and tool lifecycle boundaries
by vincentkoc · 2026-02-17
77.7%
#22873: fix(tools): enforce global inline-secret blocking for tool inputs
by Kansodata · 2026-02-21
77.6%
#19422: fix: pass session context to plugin tool hooks in toToolDefinitions
by namabile · 2026-02-17
77.4%
#7771: Hooks: wire lifecycle events and tests
by rabsef-bicrym · 2026-02-03
77.3%
#17930: fix: evaluate tool_result_persist hooks lazily to avoid race condition
by TheArkifaneVashtorr · 2026-02-16
77.2%