feat: wire remaining interception points and document the catalog

[lucasgomide]

This completes the catalog by wiring the remaining step, agent, subsystem, and flow points — pre_step/post_step, tool_selection, pre_delegation, retry_attempt, memory_write/memory_read, knowledge_retrieval, pre_code_execution, mcp_connect, flow_transition, and router_decision — each passing a typed context whose payload a hook may observe, mutate, or replace. It also adds a documentation page describing the full point/payload catalog and the interceptor contract. Stacked on #6517; part of the OSS-86 interception-hook catalog.

---

Note

Medium Risk
Hooks can alter tools, task context, memory content, flow routing, and retry behavior on hot paths; mistakes or abusive hooks could change execution semantics, though non-abort hook errors remain fail-open like existing LLM/tool hooks.

Overview
Completes the interception-hook catalog by calling dispatch() at runtime seams that were previously undocumented-only, and adds docs that describe the full point list and shared contract.

Runtime wiring adds typed contexts and InterceptionPoint dispatch for: task/flow pre_step / post_step (mutable step input/output); tool_selection when crews/agents assemble tools; pre_delegation before coworker handoff; retry_attempt on agent task retries, guardrail retries, and tool-parsing retries; memory_write / memory_read on unified memory; knowledge_retrieval on knowledge queries; pre_code_execution for flow script actions; mcp_connect before MCP connect; flow_transition and router_decision in the flow runtime (router hooks can reroute).

Docs: new Interception Hooks page (catalog, @on, mutate/replace/abort, telemetry); execution-hooks overview links to it; nav entry in docs.json.

Tests: conformance coverage for flow pre/post step, transitions, and router rerouting.

^{Reviewed by Cursor Bugbot for commit 57618f0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: de21986d-0cef-40d6-8e43-ead0f92299bf

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch luzk/hooks-catalog

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 5 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e2f88fc. Configure here.}

[cursor]

Tool selection fires twice

High Severity

TOOL_SELECTION is dispatched in both crew._prepare_tools and agent.create_agent_executor. On a normal crew run, tools prepared in the crew are passed into the agent, which fires the same point again, so hooks run twice and additive changes can duplicate tools.

Additional Locations (1)

• lib/crewai/src/crewai/agent/core.py#L1075-L1088

 

^{Reviewed by Cursor Bugbot for commit e2f88fc. Configure here.}

[cursor]

Flow pre-step ignores payload

Medium Severity

Flow PRE_STEP builds a context with payload=dumped_params and dispatches, but never applies pre_step_ctx.payload back onto the args/kwargs used to invoke the method. Unlike task PRE_STEP and flow POST_STEP, replacements and non-shared mutations have no effect.

 

^{Reviewed by Cursor Bugbot for commit e2f88fc. Configure here.}

[cursor]

Code execution hook is inert

High Severity

PRE_CODE_EXECUTION dispatches with the script string as payload, but run always executes the handler compiled at init from self.definition.code. Payload replacements and ctx.code edits never change what runs; only abort works.

 

^{Reviewed by Cursor Bugbot for commit e2f88fc. Configure here.}

[cursor]

MCP connect ignores payload

Medium Severity

MCP_CONNECT puts self.transport on the context as payload/server_params, but after dispatch the client still connects with the original self.transport and never assigns connect_ctx.payload back. Returned connection-param replacements are ignored.

 

^{Reviewed by Cursor Bugbot for commit e2f88fc. Configure here.}

[cursor]

Delegation abort is swallowed

Medium Severity

PRE_DELEGATION dispatch sits inside a broad except Exception that turns failures into a tool error string. A HookAborted from the hook is caught instead of propagating, so abort telemetry and the public abort contract do not hold for this point.

 

^{Reviewed by Cursor Bugbot for commit e2f88fc. Configure here.}