Execution Hooks & Resolution
Relevant source files
The following files were used as context for generating this wiki page:
Execution Hooks & Resolution within the MCB (Memory Context Browser) project comprise the validation logic, provenance gating, and post-execution triggers that govern how MCP (Model Context Protocol) tools are invoked and processed. This system ensures that every tool call adheres to the project's "Operation Mode Matrix," verifying that specific execution flows (such as Stdio or Hybrid) are permitted for the requested operation and that essential metadata, known as provenance, is present.
The system acts as a gatekeeper between the MCP transport layer and the functional handlers, such as the ProjectHandler. By enforcing strict validation before execution and triggering hooks—particularly for memory-related operations—after execution, MCB maintains architectural integrity and persistent context across AI agent sessions.
Execution Validation & Provenance Gating
The core of the resolution process is the validation of the ToolExecutionContext. This ensures that tools are only executed when the environment meets specific requirements regarding "Execution Flow" and "Provenance."
Operation Mode Matrix
The project defines specific allowed execution flows for different categories of tools. Validation rules prevent tools like validate_code or analyze_code from running in unauthorized flows like ServerHybrid.
| Tool Category | Allowed Execution Flows |
|---|---|
Validation Tools (validate_code, analyze_code, list_rules) | StdioOnly, ClientHybrid |
| General Tools (Search, Index, Memory, etc.) | StdioOnly, ClientHybrid, ServerHybrid |
Sources: crates/mcb-server/src/tools/validation.rs:99-114, crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:163-176
Provenance Requirements
Data-plane tools (e.g., index_repo, search_code, store_memory) require a complete "execution provenance" payload. If mandatory fields are missing or empty, the system rejects the tool call with a -32602 error code.
Required Provenance Fields:
session_id,repo_id,repo_pathoperator_id,machine_id,agent_program,model_iddelegated(boolean),timestampparent_session_id(required only ifdelegatedis true)
Sources: crates/mcb-server/src/tools/validation.rs:36-82, crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:114-142
Pre-Execution Flow
The following diagram illustrates the logical flow of a tool call being resolved and validated before reaching the handler.
The diagram shows the validation sequence where the operation mode is checked first, followed by a conditional provenance check for specific data-plane tools. Sources: crates/mcb-server/src/tools/validation.rs:25-50
Tool Resolution & Handling
Once a tool call passes validation, it is routed to specific handlers. The ProjectHandler serves as a primary example of how resource-based tools are resolved into specific CRUD actions.
Resource-Based Resolution
The project tool is a consolidated interface that routes requests based on a resource and an action.
| Resource | Description | Actions Supported |
|---|---|---|
Project | High-level project entity | Create, Get, List, Update, Delete |
Phase | Project milestones/phases | Create, Get, List, Update, Delete |
Issue | Tasks or bugs within a project | Create, Get, List, Update, Delete |
Dependency | Relationships between issues | Create, List, Delete |
Decision | Architectural or project decisions | Create, Get, List, Update, Delete |
Sources: crates/mcb-server/src/handlers/project.rs:48-56, crates/mcb-providers/tests/project_repo.rs:101-200
ID Resolution Logic
Handlers implement logic to ensure required identifiers (like project_id or org_id) are present. While project_id is mandatory for most operations, certain actions like List projects are exempt.
The sequence diagram illustrates the internal resolution of IDs and the call to the persistence layer within the ProjectHandler. Sources: crates/mcb-server/src/handlers/project.rs:35-80
Post-Execution Hooks
After a tool successfully executes, the system can trigger "Execution Hooks." These are primarily used for memory-related operations to update timelines or inject context.
Post-Tool-Use Context
A PostToolUseContext is constructed using data from the ToolExecutionContext and the result of the tool execution. This context is then processed by the HookProcessor.
Captured Hook Metadata:
session_id,parent_session_idproject_id,repo_id,worktree_idoperator_id,model_idtimestamp,delegated
Sources: crates/mcb-server/src/tools/validation.rs:136-174
Hook Trigger Logic
Hooks are triggered for operations that modify or query the system's memory and state. The process ensures that even if a tool is used successfully by an agent, the side effects (like updating a session timeline) are recorded.
This diagram shows the asynchronous triggering of hooks following successful tool execution. Sources: crates/mcb-server/src/tools/validation.rs:125-135
Conclusion
The Execution Hooks & Resolution system in MCB ensures that the AI agent's interaction with the codebase is both secure and contextually aware. By enforcing the Operation Mode Matrix and mandatory provenance, the system prevents invalid tool use. Furthermore, the post-execution hooks ensure that the persistent memory of the system is consistently updated, allowing for a seamless experience across multiple agent sessions.
Sources: README.md:10-30, AGENTS.md:140-160, crates/mcb-server/src/tools/validation.rs:10-20