Execution Boundary Hooks

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 (success or failure)	the output object, or `None` on failure

For a crew, the output payload is a CrewOutput. For a flow, it is the final flow-method result.

Hook Signature

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. 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:

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:

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 (None when status == "failed")
    status: str                    # "completed" or "failed"
    error: BaseException | None    # The exception when status == "failed"

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.

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:

@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

@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

@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

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.

Observing Failures

EXECUTION_END fires exactly once per execution, on success and on failure alike. When the run raises — a task error, a flow-method exception, or a HookAborted from an earlier point — the hook receives status="failed" with the exception in ctx.error, and the original exception still propagates out of kickoff() unchanged:

@on(InterceptionPoint.EXECUTION_END)
def report_outcome(ctx):
    if ctx.status == "failed":
        notify_policy_engine(status="failed", error=repr(ctx.error))
    else:
        notify_policy_engine(status="completed")

Two caveats: EXECUTION_END does not fire when EXECUTION_START never dispatched (an abort at start counts as the execution never beginning), and raising HookAborted from a failure-path EXECUTION_END dispatch is ignored — there is nothing left to abort, and the original error wins.

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

from crewai.hooks import clear_all_hooks

clear_all_hooks()  # Clears every point, including boundaries

Get Started

Guides

Core Concepts

MCP Integration

Tools

Observability

Learn

Telemetry

Execution Boundary Hooks

Overview

Hook Signature

Context Schema

Crew Runs vs. Flow Runs

Common Use Cases

Policy Check at Start

Input Rewriting

Output Sanitization

Observing Failures

Ordering

Managing Hooks in Tests

​Overview

​Hook Signature

​Context Schema

​Crew Runs vs. Flow Runs

​Common Use Cases

​Policy Check at Start

​Input Rewriting

​Output Sanitization

​Observing Failures

​Ordering

​Managing Hooks in Tests

​Related Documentation

Overview

Hook Signature

Context Schema

Crew Runs vs. Flow Runs

Common Use Cases

Policy Check at Start

Input Rewriting

Output Sanitization

Observing Failures

Ordering

Managing Hooks in Tests

Related Documentation