docs: group execution hooks and document all hook contexts

The hooks pages sat flat in the learn nav and only documented the LLM
and tool call contexts, with examples built on the legacy decorators.
Groups them under a collapsible "Execution Hooks" section, adds
`step-hooks` and `execution-boundary-hooks` pages covering every hook
context from source, reworks the LLM and tool pages to lead with `@on`
while keeping the decorators, and links the orphaned
`before-and-after-kickoff-hooks` page into the group.

Author: lucasgomide

docs/docs.json

@@ -373,9 +373,17 @@
                       "edge/en/learn/replay-tasks-from-latest-crew-kickoff",
                       "edge/en/learn/sequential-process",
                       "edge/en/learn/using-annotations",
-                      "edge/en/learn/execution-hooks",
-                      "edge/en/learn/llm-hooks",
-                      "edge/en/learn/tool-hooks"
+                      {
+                        "group": "Execution Hooks",
+                        "pages": [
+                          "edge/en/learn/execution-hooks",
+                          "edge/en/learn/llm-hooks",
+                          "edge/en/learn/tool-hooks",
+                          "edge/en/learn/execution-boundary-hooks",
+                          "edge/en/learn/step-hooks",
+                          "edge/en/learn/before-and-after-kickoff-hooks"
+                        ]
+                      }
                     ]
                   },
                   {

docs/edge/en/learn/execution-boundary-hooks.mdx

@@ -0,0 +1,163 @@
+---
+title: Execution Boundary Hooks
+description: Intercept the start, inputs, output, and end of crew and flow executions with the @on decorator
+mode: "wide"
+---
+
+Execution boundary hooks intercept the outermost edges of a run — before any
+work starts, when inputs are resolved, when the final result is ready, and when
+the execution finishes. They fire for both crews and flows and are the right
+place for run-level policy checks, input rewriting, and output sanitization.
+
+## Overview
+
+Four interception points cover the boundaries:
+
+| Point | When | `ctx.payload` |
+|-------|------|---------------|
+| `EXECUTION_START` | A crew or flow is about to begin | inputs `dict` |
+| `INPUT` | Resolved inputs for the execution | inputs `dict` |
+| `OUTPUT` | The final result is ready | the output object |
+| `EXECUTION_END` | The execution has finished | the output object |
+
+For a crew, the output payload is a `CrewOutput`. For a flow, it is the final
+flow-method result.
+
+## Hook Signature
+
+```python
+from crewai.hooks import on, HookAborted, InterceptionPoint
+
+@on(InterceptionPoint.EXECUTION_START)
+def boundary_hook(ctx) -> Any | None:
+    # Mutate ctx.payload in place, or
+    # return a non-None value to replace it, or
+    # raise HookAborted(reason, source) to stop the run
+    return None
+```
+
+Boundary hooks follow the standard contract: proceed (`return None`), mutate in
+place, replace by returning, or abort by raising
+[`HookAborted`](/learn/execution-hooks#aborting-an-operation). An abort at any
+boundary propagates out of `kickoff()` with its reason.
+
+## Context Schema
+
+Each point receives a typed context. All contexts share the base fields:
+
+```python
+class InterceptionContext:
+    payload: Any            # The interceptable value (see table above)
+    agent: Any = None       # Not populated at execution boundaries
+    agent_role: str | None  # Not populated at execution boundaries
+    task: Any = None        # Not populated at execution boundaries
+    crew: Any = None        # The Crew instance (crew runs only)
+    flow: Any = None        # The Flow instance (flow runs only)
+```
+
+The per-point contexts add a named alias for the payload:
+
+```python
+class ExecutionStartContext(InterceptionContext):
+    inputs: dict            # Same dict as payload
+
+class InputContext(InterceptionContext):
+    inputs: dict            # Same dict as payload
+
+class OutputContext(InterceptionContext):
+    output: Any             # The output object
+
+class ExecutionEndContext(InterceptionContext):
+    output: Any             # The output object
+```
+
+<Note>
+`ctx.inputs` aliases the **original** inputs dict, so in-place edits through
+either name are equivalent. If an earlier hook *replaced* the payload by
+returning a new dict, only `ctx.payload` is rebound — always read and write
+`ctx.payload` when hooks might chain.
+</Note>
+
+## Crew Runs vs. Flow Runs
+
+Boundary hooks fire on both runtimes, and crew execution internally rides on a
+flow runtime. During a `crew.kickoff()`, a global boundary hook therefore fires
+for the crew boundary (`ctx.crew` set, `ctx.flow` `None`) **and** for the
+internal flow (`ctx.flow` set, `ctx.crew` `None`). Discriminate by runtime:
+
+```python
+@on(InterceptionPoint.OUTPUT)
+def crew_output_only(ctx):
+    if ctx.crew is None:
+        return None  # Skip the internal flow (or a bare flow)
+    ctx.payload.raw = ctx.payload.raw.strip()
+```
+
+## Common Use Cases
+
+### Policy Check at Start
+
+```python
+@on(InterceptionPoint.EXECUTION_START)
+def enforce_policy(ctx):
+    if ctx.crew is not None and not ctx.payload.get("authorized"):
+        raise HookAborted(reason="unauthorized execution", source="access-control")
+```
+
+### Input Rewriting
+
+```python
+@on(InterceptionPoint.INPUT)
+def add_defaults(ctx):
+    if ctx.crew is None:
+        return None
+    ctx.payload.setdefault("locale", "en-US")
+    ctx.payload["topic"] = ctx.payload["topic"].strip().lower()
+```
+
+Rewritten inputs flow into task interpolation, so the run behaves as if it was
+kicked off with the modified dict.
+
+### Output Sanitization
+
+```python
+import re
+
+@on(InterceptionPoint.OUTPUT)
+def redact_emails(ctx):
+    if ctx.crew is None:
+        return None
+    ctx.payload.raw = re.sub(
+        r"\b[\w.+-]+@[\w-]+\.[\w.]+\b", "[EMAIL-REDACTED]", ctx.payload.raw
+    )
+```
+
+`OUTPUT` runs before `EXECUTION_END`, and both see the (possibly replaced)
+payload from earlier hooks; the final rewritten value is what `kickoff()`
+returns.
+
+## Ordering
+
+For a crew run the boundary order is:
+
+```
+EXECUTION_START → before_kickoff callbacks → INPUT → tasks execute → OUTPUT → EXECUTION_END
+```
+
+Hooks at the same point run in registration order, global hooks first, then
+crew-scoped hooks. Telemetry (`HookDispatchedEvent`) is emitted per dispatch.
+
+## Managing Hooks in Tests
+
+```python
+from crewai.hooks import clear_all_hooks
+
+clear_all_hooks()  # Clears every point, including boundaries
+```
+
+## Related Documentation
+
+- [Execution Hooks Overview →](/learn/execution-hooks)
+- [Step Hooks →](/learn/step-hooks)
+- [LLM Call Hooks →](/learn/llm-hooks)
+- [Tool Call Hooks →](/learn/tool-hooks)

docs/edge/en/learn/execution-hooks.mdx

@@ -64,7 +64,7 @@ from crewai.hooks import on, InterceptionPoint
 
 @on(InterceptionPoint.POST_TOOL_CALL, agents=["researcher"], tools=["web_search"])
 def log_search_results(ctx):
-    print(f"search returned: {str(ctx.payload)[:80]}")
+    print(f"search returned: {(ctx.tool_result or '')[:80]}")
 ```
 
 Applied to a method inside a `@CrewBase` class, `@on` registers a
@@ -84,30 +84,36 @@ class MyProjCrew:
 
 ## Interception point catalog
 
-`payload` is the value a hook may mutate or replace at each point.
+Each family has a detailed guide covering its context schema, payload
+semantics, and examples.
 
-### Execution boundaries
+### [Execution boundaries](/learn/execution-boundary-hooks)
 
-| Point | When | `payload` |
-|-------|------|-----------|
+| Point | When | `ctx.payload` |
+|-------|------|---------------|
 | `EXECUTION_START` | A crew or flow is about to begin | inputs `dict` |
 | `INPUT` | Resolved inputs for the execution | inputs `dict` |
 | `OUTPUT` | Final result is ready | the output object |
 | `EXECUTION_END` | A crew or flow has finished | the output object |
 
-### Model & tool boundaries
+### [Model boundaries](/learn/llm-hooks) & [tool boundaries](/learn/tool-hooks)
 
-| Point | When | `payload` |
-|-------|------|-----------|
+| Point | When | Hook receives |
+|-------|------|---------------|
 | `PRE_MODEL_CALL` | Before an LLM call | `LLMCallHookContext` |
-| `POST_MODEL_CALL` | After an LLM call | response |
+| `POST_MODEL_CALL` | After an LLM call | `LLMCallHookContext` (with `response` set) |
 | `PRE_TOOL_CALL` | Before a tool runs | `ToolCallHookContext` |
-| `POST_TOOL_CALL` | After a tool runs | tool result |
+| `POST_TOOL_CALL` | After a tool runs | `ToolCallHookContext` (with results set) |
 
-### Step points
+At these four points the hook receives the rich legacy context **directly** as
+its argument — there is no separate `ctx.payload`. Mutate `ctx.messages` /
+`ctx.tool_input` in place, and return a string from a post hook to replace the
+response / tool result.
 
-| Point | When | `payload` |
-|-------|------|-----------|
+### [Step points](/learn/step-hooks)
+
+| Point | When | `ctx.payload` |
+|-------|------|---------------|
 | `PRE_STEP` | Before a task or flow-method step | step input |
 | `POST_STEP` | After a task or flow-method step | step output |
 
@@ -147,12 +153,12 @@ def enforce_policy(ctx):
 @on(InterceptionPoint.PRE_TOOL_CALL)
 def block_dangerous_tools(ctx):
     dangerous = {"delete_file", "drop_table", "system_shutdown"}
-    if ctx.payload.tool_name in dangerous:
-        raise HookAborted(reason=f"{ctx.payload.tool_name} is blocked", source="safety-policy")
+    if ctx.tool_name in dangerous:
+        raise HookAborted(reason=f"{ctx.tool_name} is blocked", source="safety-policy")
 
 @on(InterceptionPoint.PRE_MODEL_CALL)
 def iteration_limit(ctx):
-    if ctx.payload.iterations > 15:
+    if ctx.iterations > 15:
         raise HookAborted(reason="maximum iterations exceeded", source="loop-guard")
 ```
 
@@ -161,8 +167,8 @@ def iteration_limit(ctx):
 ```python
 @on(InterceptionPoint.PRE_TOOL_CALL, tools=["send_email", "make_payment"])
 def require_approval(ctx):
-    response = ctx.payload.request_human_input(
-        prompt=f"Approve {ctx.payload.tool_name}?",
+    response = ctx.request_human_input(
+        prompt=f"Approve {ctx.tool_name}?",
         default_message="Type 'yes' to approve:",
     )
     if response.lower() != "yes":
@@ -171,8 +177,8 @@ def require_approval(ctx):
 
 ### Sanitizing outputs
 
-A non-`None` return value replaces the payload, so transformations are plain
-return statements:
+A non-`None` return value replaces the interceptable value, so transformations
+are plain return statements:
 
 ```python
 import re
@@ -182,7 +188,7 @@ def redact_keys(ctx):
     return re.sub(
         r'(api[_-]?key)["\']?\s*[:=]\s*["\']?[\w-]+',
         r"\1: [REDACTED]",
-        ctx.payload,
+        ctx.response,
         flags=re.IGNORECASE,
     )
 ```
@@ -254,10 +260,11 @@ Differences from `@on`:
 - They cover **only** the four model/tool points — no execution boundaries, no
   steps.
 - Blocking is `return False`, with no abort reason or source attached.
-- They receive rich point-specific contexts — `LLMCallHookContext` (with full
-  executor access) and `ToolCallHookContext` — the same objects `@on` exposes
-  as `ctx.payload` at the `PRE_MODEL_CALL` / `PRE_TOOL_CALL` points.
-- Crew-scoping uses the `*_crew` decorator variants inside `@CrewBase` classes.
+- They receive the same rich contexts — `LLMCallHookContext` (with full
+  executor access) and `ToolCallHookContext` — that `@on` hooks receive at the
+  model/tool points.
+- Crew-scoping works the same way: apply the decorator to a method inside a
+  `@CrewBase` class.
 - They support the same `agents=` / `tools=` filters.
 
 You might still prefer them for existing codebases that already use