feat: Add tool_pre_invoke and tool_post_invoke plugin hooks #686

shams858 · 2025-08-08T14:32:54Z

Summary

Implements tool_pre_invoke and tool_post_invoke plugin hooks following the established pattern. This enables plugins to intercept, modify, and monitor tool invocations throughout the system. Closes #682

Changes Made

Core Framework

Plugin Types: Added ToolPreInvokePayload, ToolPostInvokePayload, ToolPreInvokeResult, ToolPostInvokeResult models
Hook Types: Extended HookType enum with TOOL_PRE_INVOKE and TOOL_POST_INVOKE
Base Plugin: Added default implementations of tool_pre_invoke() and tool_post_invoke() methods
Plugin Manager: Implemented tool hook executors and orchestration methods matching prompt hook patterns
Utility Functions: Added pre_tool_matches() and post_tool_matches() for condition evaluation

Service Integration

ToolService: Integrated plugin manager and hook invocation into invoke_tool() workflow
Error Handling: Added proper PluginViolationError handling and fail_on_plugin_error support
Context Management: Implemented request ID generation and plugin context lifecycle

Plugin Updates

SearchReplacePlugin: Added tool argument and result transformation capabilities
PIIFilterPlugin: Enhanced with intelligent nested PII detection for complex tool results
- Recursive traversal of dictionaries, lists, and JSON strings
- Deep inspection of nested structures like {'content': [{'text': '{"username": "[email protected]"}'}]}
- Proper masking and re-serialization of modified data
Plugin Manifests: Updated to declare tool hook capabilities

Testing

Unit Tests: Comprehensive test coverage for plugin manager tool hooks
Test Fixtures: Created valid_tool_hooks.yaml configuration for tool-specific testing

Key Features

✅ Consistency: Follows exact same patterns as existing prompt hooks
✅ Flexibility: Supports blocking, modification, and monitoring use cases
✅ Performance: Reuses existing plugin executor infrastructure
✅ Error Resilience: Proper timeout and error handling
✅ Backwards Compatibility: No breaking changes to existing functionality
✅ Deep Inspection: Intelligent PII detection in nested/JSON data structures

Testing

All existing tests pass
New unit tests for tool hook functionality
PII detection tested with complex nested JSON structures

Implements: #682

crivetimihai · 2025-08-08T21:11:22Z

Wow, awesome! We'll test soon!

Signed-off-by: Shamsul Arefin <[email protected]>

…cstring's Raises section. Signed-off-by: Shamsul Arefin <[email protected]>

Signed-off-by: Mihai Criveti <[email protected]>

crivetimihai

PR Review: Tool Hooks for Plugin System

Passed: make autoflake isort black pre-commit doctest test smoketest lint-web flake8 pylint

Branch: `feature-pre-post-invoke-tool-hook`

Test Results Summary

All tests and linters passed after rebasing on main:

✅ Doctest: 443 passed, 8 skipped
✅ Test Suite: 1307 passed, 10 skipped, 49 warnings
✅ Smoketest: Passed with TLS enabled
✅ Lint-web: No security vulnerabilities found
✅ Flake8: Clean (no issues)
✅ Pylint: 10.00/10 (only 2 TODO comments in sampling.py)
✅ Coverage: 80% overall

Key Features Added

1. Plugin Framework Tool Hooks

Added tool_pre_invoke and tool_post_invoke hooks to the plugin system
New payload types: ToolPreInvokePayload and ToolPostInvokePayload
Plugins can now intercept, modify, or block tool invocations
Proper error handling with PluginViolationError for blocked requests

2. PII Filter Enhancements

Extended PII detection to tool arguments and results
Added intelligent nested data structure processing
Support for recursive traversal of complex tool payloads
Maintains detection statistics and metadata

3. Tool Service Integration

Integrated plugin manager into tool service
Pre-invoke hooks can modify tool arguments before execution
Post-invoke hooks can filter/modify tool results
Proper context passing with request IDs and server IDs
Maintains passthrough headers functionality - properly integrated with new plugin hooks

Minor Issues Found

1. Debug Code Left In

PII filter contains debug print statements that should be removed before merge
Lines in plugins/pii_filter/pii_filter.py with print() calls

Recommendations for Merge

Must Fix Before Merge:

Remove debug print statements from PII filter plugin
Fix duplicate database field in Gateway model (remove duplicate at line 1124)

Nice to Have:

Add integration tests specifically for tool hooks
Add examples of tool hook usage in plugin documentation
Consider adding performance benchmarks for plugin processing overhead

Files Changed Summary

Modified Core Files:

mcpgateway/services/tool_service.py - Added plugin hook integration with passthrough headers support
mcpgateway/plugins/framework/base.py - Added tool hook methods
mcpgateway/plugins/framework/manager.py - Implemented tool hook orchestration
mcpgateway/plugins/framework/plugin_types.py - New tool payload types
mcpgateway/plugins/framework/utils.py - Added tool hook matchers

Modified Plugins:

plugins/pii_filter/pii_filter.py - Extended with tool hook support (has debug prints)
plugins/regex_filter/search_replace.py - Minor improvements

Test Files Added:

tests/unit/mcpgateway/plugins/fixtures/configs/valid_tool_hooks.yaml - Tool hook test fixture

Testing Command Sequence

# After rebase
git rebase origin/main

# Run all tests and linters
make doctest test smoketest lint-web flake8 pylint

# All passed successfully!

Code Quality Metrics

Coverage: 80%
Pylint Score: 10.00/10
Security: No vulnerabilities found
Performance: All tests complete in ~32 seconds

No Breaking Changes

✅ The passthrough headers feature is fully maintained and working correctly with the new plugin hooks.

Next Steps

Remove debug print statements from PII filter
Fix duplicate database field
Update documentation for the new tool hooks feature
Consider adding more comprehensive integration tests for the new tool hooks feature

araujof

Nice work! I tested the examples and they work with a sample server.

Please address the change requests here.

It would be great to add documentation in the plugins and in the general docs for the tool hook usage, as well as having some specific tests for the tool hooks.

crivetimihai · 2025-08-09T10:56:20Z

Working on a few logging and cleanup updates.

Signed-off-by: Mihai Criveti <[email protected]>

Implemented

* feat: add tool hooks to plugin system Signed-off-by: Shamsul Arefin <[email protected]> * feat: connect plugins to tool invoke, pii_filter improvements Signed-off-by: Shamsul Arefin <[email protected]> * Add PluginViolationError: If plugin blocks tool invocation. to the docstring's Raises section. Signed-off-by: Shamsul Arefin <[email protected]> * Apply linter fixes * Rebase and lint Signed-off-by: Mihai Criveti <[email protected]> * Update logging and docs Signed-off-by: Mihai Criveti <[email protected]> --------- Signed-off-by: Shamsul Arefin <[email protected]> Signed-off-by: Mihai Criveti <[email protected]> Co-authored-by: Shamsul Arefin <[email protected]> Co-authored-by: Mihai Criveti <[email protected]>

shams858 requested review from crivetimihai, kevalmahajan and madhav165 as code owners August 8, 2025 14:32

Shamsul Arefin and others added 4 commits August 8, 2025 23:26

feat: add tool hooks to plugin system

86009f4

Signed-off-by: Shamsul Arefin <[email protected]>

feat: connect plugins to tool invoke, pii_filter improvements

e381241

Signed-off-by: Shamsul Arefin <[email protected]>

Add PluginViolationError: If plugin blocks tool invocation. to the do…

b6b8daa

…cstring's Raises section. Signed-off-by: Shamsul Arefin <[email protected]>

Apply linter fixes

27e79ff

araujof self-requested a review August 8, 2025 22:33

araujof added the enhancement New feature or request label Aug 8, 2025

Rebase and lint

11a42b2

Signed-off-by: Mihai Criveti <[email protected]>

crivetimihai force-pushed the feature-pre-post-invoke-tool-hook branch from 6c10096 to 11a42b2 Compare August 8, 2025 22:41

crivetimihai approved these changes Aug 8, 2025

View reviewed changes

araujof previously requested changes Aug 9, 2025

View reviewed changes

Update logging and docs

7e478c7

Signed-off-by: Mihai Criveti <[email protected]>

crivetimihai merged commit fdc2edb into IBM:main Aug 9, 2025
36 checks passed

crivetimihai mentioned this pull request Aug 10, 2025

[Feature Request]: ABAC Virtual Server Support #706

Open

10 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add tool_pre_invoke and tool_post_invoke plugin hooks #686

feat: Add tool_pre_invoke and tool_post_invoke plugin hooks #686

Uh oh!

shams858 commented Aug 8, 2025 •

edited by crivetimihai

Loading

Uh oh!

crivetimihai commented Aug 8, 2025

Uh oh!

crivetimihai left a comment

Uh oh!

araujof left a comment

Uh oh!

crivetimihai commented Aug 9, 2025

Uh oh!

Uh oh!

Uh oh!

feat: Add tool_pre_invoke and tool_post_invoke plugin hooks #686

feat: Add tool_pre_invoke and tool_post_invoke plugin hooks #686

Uh oh!

Conversation

shams858 commented Aug 8, 2025 • edited by crivetimihai Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes Made

Core Framework

Service Integration

Plugin Updates

Testing

Key Features

Testing

Uh oh!

crivetimihai commented Aug 8, 2025

Uh oh!

crivetimihai left a comment

Choose a reason for hiding this comment

PR Review: Tool Hooks for Plugin System

Branch: feature-pre-post-invoke-tool-hook

Test Results Summary

Key Features Added

1. Plugin Framework Tool Hooks

2. PII Filter Enhancements

3. Tool Service Integration

Minor Issues Found

1. Debug Code Left In

Recommendations for Merge

Must Fix Before Merge:

Nice to Have:

Files Changed Summary

Modified Core Files:

Modified Plugins:

Test Files Added:

Testing Command Sequence

Code Quality Metrics

No Breaking Changes

Next Steps

Uh oh!

araujof left a comment

Choose a reason for hiding this comment

Uh oh!

crivetimihai commented Aug 9, 2025

Uh oh!

Uh oh!

Uh oh!

shams858 commented Aug 8, 2025 •

edited by crivetimihai

Loading

Branch: `feature-pre-post-invoke-tool-hook`