#11071: Plugins: add tool_result_received hook for output interception
docs
agents
Cluster:
Plugin Hook Enhancements
## Summary
- Add a new `tool_result_received` plugin hook that runs **after tool execution** but **before results reach the agent**, enabling plugins to modify or block tool outputs for security guardrails and content filtering.
- Runs sequentially with async support, complementing the existing fire-and-forget `after_tool_call` hook.
- Includes review fixes: preserve original params type (`unknown`), fix `runModifyingHook` type cast, clarify `durationMs` semantics.
Based on #10328 by @ThomasLWang with review feedback from greptile-apps addressed.
## Test plan
- [x] `pnpm build` passes
- [x] `pnpm check` (tsgo + oxlint + oxfmt) passes
- [x] `pnpm test` — 219 tests pass
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Thomas <thomas@openguardrails.com>
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds a new plugin lifecycle hook, `tool_result_received`, which runs after a tool executes but before its output is delivered back into the agent loop. Tool execution is now wrapped so plugins can (a) modify tool params pre-execution via `before_tool_call` and (b) modify/block tool results post-execution via the new sequential hook, while `after_tool_call` remains parallel fire-and-forget. The hook runner (`src/plugins/hooks.ts`) gains a sequential “modifying hook” runner that supports both sync and async handlers and merges results in priority order, including preserving explicit `null` overrides for tool results. Documentation and changelog are updated to describe the new interception point in the agent loop.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk.
- Changes are localized to plugin hook plumbing and tool wrapping, with clear semantics, idempotent wrapping, and explicit handling for null overrides; no remaining issues from prior review threads were found in the current commit.
- No files require special attention
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#16028: feat/before-tool-result
by ambushalgorithm · 2026-02-14
82.5%
#22068: Add tool:before/tool:after internal hook events
by yhindy · 2026-02-20
79.9%
#10678: feat(hooks): wire after_tool_call hook into tool execution pipeline
by yassinebkr · 2026-02-06
79.8%
#17930: fix: evaluate tool_result_persist hooks lazily to avoid race condition
by TheArkifaneVashtorr · 2026-02-16
78.5%
#6095: feat(gateway): support modular guardrails extensions for securing a...
by Reapor-Yurnero · 2026-02-01
78.5%
#17667: feat: tool-hooks extension — run shell commands on tool calls
by FaradayHunt · 2026-02-16
78.1%
#6405: feat(security): Add HTTP API security hooks for plugin scanning
by masterfung · 2026-02-01
76.8%
#20580: feat(hooks): bridge after_tool_call to internal hook handler system
by CryptoKrad · 2026-02-19
76.1%
#17346: feat(hooks): add message_persist hook for all transcript messages
by clawee-vanguard · 2026-02-15
75.6%
#14873: [Feature]: Extend before_agent_start hook context with Model, Tools...
by akv2011 · 2026-02-12
75.6%