[rwzdk]

Fixes #8630

Note: This PR was developed with the assistance of an AI coding agent under human review. Maintainers: please apply the llm-generated label.

Problem

Every code example in the hooks guides that defines a @CrewBase class imports it with:

from crewai import CrewBase

That import fails on current code. CrewBase is defined in crewai.project.crew_base and re-exported only from crewai.project (lib/crewai/src/crewai/project/__init__.py); it is not imported in crewai/__init__.py and is not in its __all__. Verified at runtime against main:

>>> from crewai import CrewBase
ImportError: cannot import name 'CrewBase' from 'crewai' (.../lib/crewai/src/crewai/__init__.py)
>>> from crewai.project import CrewBase  # OK

Readers copying these examples get an ImportError on the very first line.

How this regressed

The v1.14.x docs snapshots used the correct from crewai.project import CrewBase in the concepts/guides pages (e.g. docs/v1.14.7/en/concepts/agents.mdx), but the learn/ hooks pages never did, and the v1.15.0 docs restructure dropped the corrected usages. The wrong import survives in all versioned snapshots and, for the translated pages, in edge as well (edge/en was already corrected; edge/ko and edge/pt-BR were not).

What changed

One-line replacement of from crewai import CrewBase with from crewai.project import CrewBase (matching the style already used by edge/en/learn/execution-hooks.mdx and the rest of the docs, e.g. docs/edge/en/concepts/agents.mdx) in the pages that still serve the broken snippet:

• docs/v1.15.30/ (current latest snapshot): en, ar, ko, pt-BR — learn/before-and-after-kickoff-hooks.mdx, learn/execution-hooks.mdx, learn/llm-hooks.mdx, learn/tool-hooks.mdx (12 files)
• docs/edge/: ko, pt-BR — learn/llm-hooks.mdx, learn/tool-hooks.mdx (4 files)

Older versioned snapshot directories are intentionally left untouched.

Verification

• grep confirms zero remaining from crewai import CrewBase under docs/v1.15.30 and docs/edge; all 20 changed lines now read from crewai.project import CrewBase.
• Runtime check against main (paths above) shows the old import raises ImportError and the new one succeeds.
• Docs-only change; no library code touched.

---

Note

Low Risk
Documentation-only updates to code examples; no runtime or library behavior is affected.

Overview
Updates crew-scoped hook snippets in docs/edge LLM and tool hook guides (ar, en, ko, pt-BR) so they match the current @on / InterceptionPoint API instead of legacy @before_*_call_crew / @after_*_call_crew decorators.

Examples now import CrewBase and crew from crewai.project, use @on(InterceptionPoint.PRE_MODEL_CALL) or PRE_TOOL_CALL, and show tool validation via HookAborted rather than return False. Crew-scoped samples are shortened (single pre-hook, leaner Crew(...) construction). Docs-only; no library changes.

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

[mintlify]

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 416f80e.

Approve preview

[strix-security]

Strix Security Review

Warning

This pull request has 7 commits after the last Strix review (fcc2cc5). Strix has not reviewed these changes.
Automatic review on push is off for this repository. To review the latest changes, tag @strix-security in a comment, or turn on re-review on push.

✅ No open security findings.

PR summary: Corrects the `@​CrewBase` import in the hooks documentation so examples use `from crewai.project import CrewBase` instead of the broken `from crewai import CrewBase`, applied across the current versioned docs snapshot and the Korean/Portuguese `edge` pages.

Review summary

The PR is documentation-only: every changed file under docs/ updates a single import line inside fenced Python hook examples, replacing from crewai import CrewBase with from crewai.project import CrewBase so the snippets match the actual re-export location and no longer raise ImportError when copied. No library code, CI configuration, scripts, or executable paths are modified, so the diff introduces no attacker-reachable data flow, no new input handling, and removes no security control. No security issues were identified in the changed lines.

_{Review 1 on this PR · fcc2cc5 · requested Oct 26 19:11 UTC when the PR was opened}

---

Reviewed by Strix
_{Re-run review · Configure security review settings}

[Vidit-Ostwal]

The CrewBase import claim is right: it is exported from crewai.project, not crewai, so from crewai import CrewBase raises ImportError. A few things need to change before this matches how these docs are maintained.

Drop the docs/v1.15.30/ edits. Trees under docs/v*/ are frozen release snapshots, and DOCS_TRANSLATIONS.md says not to edit them. Please revert those 12 files. The live pages are under docs/edge/.

The four docs/edge import swaps are not enough. docs/edge/ko and docs/edge/pt-BR llm-hooks.mdx / tool-hooks.mdx still import before_llm_call_crew, after_llm_call_crew, before_tool_call_crew, and after_tool_call_crew. Those names are no longer exported from crewai.hooks. The current English pages register crew-scoped hooks with @on(InterceptionPoint....). Please sync those sections from:

• docs/edge/en/learn/llm-hooks.mdx
• docs/edge/en/learn/tool-hooks.mdx

Translate the prose only, and keep the code blocks aligned with English.

English and Arabic edge pages still do not copy-paste. On docs/edge/en, the crew-scoped examples in llm-hooks.mdx and tool-hooks.mdx use @CrewBase and @crew without importing them (from crewai.project import CrewBase, crew, plus Crew and Process where the snippet uses those names). docs/edge/ar has the same blocks with no imports, and still uses the removed *_crew decorators. Update English first, then sync ar, ko, and pt-BR together.

Kickoff and execution hooks on edge for ko and pt-BR already use from crewai.project import CrewBase. This was not introduced in the v1.15.0 restructure: the learn hooks pages have used from crewai import CrewBase since at least v1.10, while the concepts pages already imported from crewai.project.

[rwzdk]

Thanks for the detailed review — all three points are addressed in 3df8106.

1. Reverted the docs/v1.15.30/ edits (12 files)

Confirmed against the actual PR diff (gh pr diff 8632 --name-only): the original commit touched 16
files, 12 of them under docs/v1.15.30/. All 12 are reverted, so the PR now contains zero
snapshot changes.

The rule is stated in two places, which I read before reverting:

• AGENTS.md → "Changing Docs", item 2: "Do not modify files under docs/v*/. Those are frozen
  release snapshots managed by devtools."
• DOCS_TRANSLATIONS.md, Step 1: "Only process *.mdx under docs/edge/en/. Do not edit
  docs/v*/ snapshots."

2. English live pages first

docs/edge/en/learn/llm-hooks.mdx and docs/edge/en/learn/tool-hooks.mdx — "2. Crew-Scoped Hooks".
I read each snippet before adding imports, and only added names the block actually uses:

• llm-hooks.mdx uses @CrewBase, @crew, Crew (annotation + constructor) and Process.sequential
  → added from crewai.project import CrewBase, crew and from crewai import Crew, Process.
• tool-hooks.mdx uses those four plus raise HookAborted(...) inside the crew method, which was
  also unimported in that block → same two lines added, and HookAborted added to the existing
  from crewai.hooks import … line.

Examples are otherwise unchanged — no restructuring. CrewBase/crew from crewai.project and
Crew/Process from crewai match the live package exports (lib/crewai/src/crewai/project/__init__.py
__all__, lib/crewai/src/crewai/__init__.py), and the import style follows the neighbouring
docs/edge/en/learn/execution-hooks.mdx, which already does from crewai.project import CrewBase.

3. Synced ar, ko, pt-BR

Before rewriting anything I verified the removed names really are gone: grep -rn "before_llm_call_crew|after_llm_call_crew|before_tool_call_crew|after_tool_call_crew" lib/crewai/src/ lib/crewai-core/src/ → no matches, and crewai/hooks/__init__.py.__all__ exports only
before_llm_call, after_llm_call, before_tool_call, after_tool_call, on, InterceptionPoint, …

The crew-scoped block in all six localized pages is now byte-identical to English (checked by
comparing the extracted fences), prose left translated. Two notes on what that implies:

• ar gained the imports it never had and lost the *_crew decorators.
• ko/pt-BR previously demonstrated two crew-scoped hooks (@before_*_crew + @after_*_crew);
  English's block has one, so syncing dropped the second one. The after-hook pattern is still covered
  by each page's "Legacy Decorators" section — say the word if you would rather I keep a second
  @on(InterceptionPoint.POST_*_CALL) method there instead.

4. Scope

The PR is now 8 files, all under docs/edge/*/learn/, and no docs/v*/.

Verification

Scope, against the merge base 5d4f45b9:

$ git diff --name-only 5d4f45b9...HEAD -- 'docs/v*/' | wc -l
0
$ git diff --name-only 5d4f45b9...HEAD
docs/edge/ar/learn/llm-hooks.mdx
docs/edge/ar/learn/tool-hooks.mdx
docs/edge/en/learn/llm-hooks.mdx
docs/edge/en/learn/tool-hooks.mdx
docs/edge/ko/learn/llm-hooks.mdx
docs/edge/ko/learn/tool-hooks.mdx
docs/edge/pt-BR/learn/llm-hooks.mdx
docs/edge/pt-BR/learn/tool-hooks.mdx

Removed decorators across the changed pages: 0 matches. Every @CrewBase / @crew fence resolves
its names by parsing each fenced block with ast and reading its ImportFrom nodes:

  docs/edge/ar/learn/llm-hooks.mdx     fence@124 uses CrewBase,crew,Crew,Process: OK
  docs/edge/ar/learn/tool-hooks.mdx    fence@123 uses CrewBase,crew,Crew,Process: OK
  docs/edge/en/learn/llm-hooks.mdx     fence@115 uses CrewBase,crew,Crew,Process: OK
  docs/edge/en/learn/tool-hooks.mdx    fence@124 uses CrewBase,crew,Crew,Process: OK
  docs/edge/ko/learn/llm-hooks.mdx     fence@112 uses CrewBase,crew,Crew,Process: OK
  docs/edge/ko/learn/tool-hooks.mdx    fence@110 uses CrewBase,crew,Crew,Process: OK
  docs/edge/pt-BR/learn/llm-hooks.mdx  fence@112 uses CrewBase,crew,Crew,Process: OK
  docs/edge/pt-BR/learn/tool-hooks.mdx fence@110 uses CrewBase,crew,Crew,Process: OK
RESULT: PASS

Mintlify: there is no package.json/justfile in docs/; the only docs tooling is the Mint CLI
(.github/workflows/docs-broken-links.yml pins [email protected], and AGENTS.md points at
mintlify dev / mintlify broken-links). I installed that exact pin and ran mint validate. A full
tree validate is impractical (34,787 mdx files), so I reproduced the CI's own prune step in a scratch
copy — keeps edge + the default version, prunes the other v* trees — giving 1,537 pages, all 8
changed files among them:

$ mint validate --no-telemetry
success build validation passed        # exit 0

One caveat to be straight about: mint validate does not pass on the pristine tree, but not
because of this PR. It aborts on a pre-existing frontmatter parse error in
edge/ko/tools/ai-ml/ragtool.mdx (line 1, col 13 — an unterminated backtick in description:), plus
its v1.15.30 copy. That file is untouched here (git diff 5d4f45b9...HEAD on it is empty) and fails
identically at the base commit, so I quarantined those two pages to get a clean signal on the rest.
Happy to open a separate PR for it if useful.

mint broken-links also runs, but in the pruned scratch it reports 344 pre-existing broken links
across 70 files including the English hooks pages themselves — while all of those targets do exist and
are in docs.json navigation, so I do not trust that signal outside a full mintlify build and did
not chase it. It cannot be affected by this change regardless: of the 192 added/removed content lines
in the diff, 0 contain a Markdown link or an /edge/ path — every changed line is inside a

### Out of scope, flagging it

`docs/edge/{ar,ko,pt-BR}/learn/execution-hooks.mdx` still import the removed `*_crew` names too. You
scoped this round to `llm-hooks`/`tool-hooks`, so I left them alone to keep the diff down — I can fold
them in here or do a follow-up PR, whichever you prefer.

Prepared with an AI coding agent.

[rwzdk]

@Vidit-Ostwal the requested changes are pushed — could you take another look when you have a moment?

• every edit under docs/v1.15.30/ is gone; the diff is now docs/edge/** only
• English learn/llm-hooks.mdx and learn/tool-hooks.mdx crew-scoped examples import what they use (from crewai.project import CrewBase, crew, plus Crew / Process / HookAborted where the snippet references them)
• ar, ko and pt-BR were synced from the English pages: prose translated, code fences byte-identical, and the removed before_*_crew / after_*_crew decorators are gone from the pages this touches

Not touched, flagging rather than expanding scope: docs/edge/{ar,ko,pt-BR}/learn/execution-hooks.mdx still imports those removed decorators. Happy to fold that in here or send it separately, your call.