docs: snapshot and changelog for v1.14.8a5 (#6329)

`StateProxy` looked like a thread-safety boundary, but it only protected
a small slice of state operations. Some examples of operations that were
not covered:

- `self.state.counter += 1`, `self.state["counter"] += 1` (increments)
- `self.state.user.profile.score += 1` (nested object mutations)
- `self.state.config["limits"]["max"] = 10` (mutation through model fields)
- `self.state.items[0].status = "done"` (list/container mutations)

This commit decided to remove it completely for simplicity and
performance:

- Simpler runtime code
- attr read: 24x faster, attr write: 27x faster, list append: 19x faster (local benchmark)
- Clearer concurrency contract (lifecycle locks remain, but arbitrary
  shared state mutation is not presented as thread-safe)

conftest.py

@@ -134,17 +134,21 @@ def bedrock_host_matcher(r1: Request, r2: Request) -> bool:  # type: ignore[no-a
     )
 
 
-def _patched_make_vcr_request(httpx_request: Any, **kwargs: Any) -> Any:
+def _patched_make_vcr_request(
+    httpx_request: Any, real_request_body: Any = None, **kwargs: Any
+) -> Any:
     """Patched version of VCR's _make_vcr_request that handles binary content.
 
     The original implementation fails on binary request bodies (like file uploads)
     because it assumes all content can be decoded as UTF-8.
     """
-    raw_body = httpx_request.read()
-    try:
-        body = raw_body.decode("utf-8")
-    except UnicodeDecodeError:
-        body = base64.b64encode(raw_body).decode("ascii")
+    raw_body = real_request_body if real_request_body is not None else httpx_request.read()
+    body: Any = raw_body
+    if isinstance(raw_body, bytes):
+        try:
+            body = raw_body.decode("utf-8")
+        except UnicodeDecodeError:
+            body = base64.b64encode(raw_body).decode("ascii")
     uri = str(httpx_request.url)
     headers = dict(httpx_request.headers)
     return Request(httpx_request.method, uri, body, headers)

docs/docs.json

@@ -397,7 +397,14 @@
                     "group": "Build",
                     "pages": [
                       "edge/en/enterprise/features/automations",
-                      "edge/en/enterprise/features/crew-studio",
+                      {
+                        "group": "Crew Studio",
+                        "icon": "pencil",
+                        "pages": [
+                          "edge/en/enterprise/features/crew-studio",
+                          "edge/en/enterprise/features/merged-step-card"
+                        ]
+                      },
                       "edge/en/enterprise/features/marketplace",
                       "edge/en/enterprise/features/agent-repositories",
                       "edge/en/enterprise/features/tools-and-integrations",
@@ -921,7 +928,14 @@
                     "group": "Build",
                     "pages": [
                       "v1.14.7/en/enterprise/features/automations",
-                      "v1.14.7/en/enterprise/features/crew-studio",
+                      {
+                        "group": "Crew Studio",
+                        "icon": "pencil",
+                        "pages": [
+                          "v1.14.7/en/enterprise/features/crew-studio",
+                          "v1.14.7/en/enterprise/features/merged-step-card"
+                        ]
+                      },
                       "v1.14.7/en/enterprise/features/marketplace",
                       "v1.14.7/en/enterprise/features/agent-repositories",
                       "v1.14.7/en/enterprise/features/tools-and-integrations",
@@ -8547,7 +8561,14 @@
                     "group": "Construir",
                     "pages": [
                       "edge/pt-BR/enterprise/features/automations",
-                      "edge/pt-BR/enterprise/features/crew-studio",
+                      {
+                        "group": "Crew Studio",
+                        "icon": "pencil",
+                        "pages": [
+                          "edge/pt-BR/enterprise/features/crew-studio",
+                          "edge/pt-BR/enterprise/features/merged-step-card"
+                        ]
+                      },
                       "edge/pt-BR/enterprise/features/marketplace",
                       "edge/pt-BR/enterprise/features/agent-repositories",
                       "edge/pt-BR/enterprise/features/tools-and-integrations",
@@ -9048,7 +9069,14 @@
                     "group": "Construir",
                     "pages": [
                       "v1.14.7/pt-BR/enterprise/features/automations",
-                      "v1.14.7/pt-BR/enterprise/features/crew-studio",
+                      {
+                        "group": "Crew Studio",
+                        "icon": "pencil",
+                        "pages": [
+                          "v1.14.7/pt-BR/enterprise/features/crew-studio",
+                          "v1.14.7/pt-BR/enterprise/features/merged-step-card"
+                        ]
+                      },
                       "v1.14.7/pt-BR/enterprise/features/marketplace",
                       "v1.14.7/pt-BR/enterprise/features/agent-repositories",
                       "v1.14.7/pt-BR/enterprise/features/tools-and-integrations",
@@ -16411,7 +16439,14 @@
                     "group": "빌드",
                     "pages": [
                       "edge/ko/enterprise/features/automations",
-                      "edge/ko/enterprise/features/crew-studio",
+                      {
+                        "group": "Crew Studio",
+                        "icon": "pencil",
+                        "pages": [
+                          "edge/ko/enterprise/features/crew-studio",
+                          "edge/ko/enterprise/features/merged-step-card"
+                        ]
+                      },
                       "edge/ko/enterprise/features/marketplace",
                       "edge/ko/enterprise/features/agent-repositories",
                       "edge/ko/enterprise/features/tools-and-integrations",
@@ -16924,7 +16959,14 @@
                     "group": "빌드",
                     "pages": [
                       "v1.14.7/ko/enterprise/features/automations",
-                      "v1.14.7/ko/enterprise/features/crew-studio",
+                      {
+                        "group": "Crew Studio",
+                        "icon": "pencil",
+                        "pages": [
+                          "v1.14.7/ko/enterprise/features/crew-studio",
+                          "v1.14.7/ko/enterprise/features/merged-step-card"
+                        ]
+                      },
                       "v1.14.7/ko/enterprise/features/marketplace",
                       "v1.14.7/ko/enterprise/features/agent-repositories",
                       "v1.14.7/ko/enterprise/features/tools-and-integrations",
@@ -24467,7 +24509,14 @@
                     "group": "البناء",
                     "pages": [
                       "edge/ar/enterprise/features/automations",
-                      "edge/ar/enterprise/features/crew-studio",
+                      {
+                        "group": "استوديو الطاقم",
+                        "icon": "pencil",
+                        "pages": [
+                          "edge/ar/enterprise/features/crew-studio",
+                          "edge/ar/enterprise/features/merged-step-card"
+                        ]
+                      },
                       "edge/ar/enterprise/features/marketplace",
                       "edge/ar/enterprise/features/agent-repositories",
                       "edge/ar/enterprise/features/tools-and-integrations",
@@ -24980,7 +25029,14 @@
                     "group": "البناء",
                     "pages": [
                       "v1.14.7/ar/enterprise/features/automations",
-                      "v1.14.7/ar/enterprise/features/crew-studio",
+                      {
+                        "group": "استوديو الطاقم",
+                        "icon": "pencil",
+                        "pages": [
+                          "v1.14.7/ar/enterprise/features/crew-studio",
+                          "v1.14.7/ar/enterprise/features/merged-step-card"
+                        ]
+                      },
                       "v1.14.7/ar/enterprise/features/marketplace",
                       "v1.14.7/ar/enterprise/features/agent-repositories",
                       "v1.14.7/ar/enterprise/features/tools-and-integrations",

docs/edge/ar/changelog.mdx

@@ -4,6 +4,83 @@ description: "تحديثات المنتج والتحسينات وإصلاحات
 icon: "clock"
 mode: "wide"
 ---
+<Update label="24 يونيو 2026">
+  ## v1.14.8a5
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a5)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - جعل المراجع التصريحية تعمل عبر التدفقات والفرق (#6326)
+
+  ### إصلاحات الأخطاء
+  - إصلاح مدخلات بدء حالة تدفق مخطط JSON (#6325)
+
+  ### الوثائق
+  - وضع بطاقة واحدة لكل خطوة تحت استوديو الفريق وإزالة لافتة التوزيع (AGE-107) (#6317)
+  - تحديث اللقطة وسجل التغييرات للإصدار v1.14.8a4 (#6319)
+
+  ### إعادة الهيكلة
+  - إزالة `StateProxy` من الوصول إلى حالة التدفق (#6327)
+
+  ## المساهمون
+
+  @jessemiller, @vinibrsl
+
+</Update>
+
+<Update label="24 يونيو 2026">
+  ## v1.14.8a4
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a4)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - دعم تدفقات المحادثة في واجهة سطر الأوامر TUI.
+
+  ### إصلاحات الأخطاء
+  - إصلاح مسار التوجيه الرمزي في استخراج أرشيف المهارات.
+  - التحقق من صحة مسارات تعريف التدفق الإعلاني.
+
+  ### الوثائق
+  - تحديث اللقطة وسجل التغييرات للإصدار v1.14.8a3.
+
+  ## المساهمون
+
+  @lorenzejay, @theCyberTech, @vinibrsl
+
+</Update>
+
+<Update label="23 يونيو 2026">
+  ## v1.14.8a3
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a3)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة تحميل تدفق موحد إعلاني
+  - تحسين تجربة بدء تشغيل crewai run
+  - دمج `crewai run` و `crewai flow kickoff`
+  - الحفاظ على تقدم طريقة التدفق مرئيًا للفرق المتداخلة
+  - إضافة دعم واجهة سطر الأوامر الإعلانية للتدفق
+  - السماح باستخدام `@router()` كطريقة بدء لتدفق
+  - إضافة مخططات مخرجات مكتوبة لأدوات CrewAI
+
+  ### إصلاحات الأخطاء
+  - تثبيت opentelemetry على ~=1.42.0
+
+  ### الوثائق
+  - إضافة صفحة استوديو "بطاقة واحدة لكل خطوة"
+
+  ## المساهمون
+
+  @jessemiller, @joaomdmoura, @lucasgomide, @vinibrsl
+
+</Update>
+
 <Update label="18 يونيو 2026">
   ## v1.14.8a2
 
@@ -64,7 +141,7 @@ mode: "wide"
   - تنفيذ أدوات تشغيل تعريف التدفق بدون كود Python
   - دفع التغذية الراجعة البشرية من تعريف التدفق
   - توصيل التكوين والاستمرارية من FlowDefinition إلى وقت التشغيل
-  - إضافة `crewai run --definition` التجريبية للتدفقات
+  - إضافة `crewai run --definition` للتدفقات التصريحية
   - دعم تراجع نشر ZIP وتشغيل مشاريع الطاقم بتنسيق JSON
   - تقديم الطواقم بتنسيق JSON أولاً
 

docs/edge/ar/concepts/flows.mdx

@@ -959,7 +959,7 @@ source .venv/bin/activate
 بعد تفعيل البيئة الافتراضية، يمكنك تشغيل التدفق بتنفيذ أحد الأوامر التالية:
 
 ```bash
-crewai flow kickoff
+crewai run
 ```
 
 أو
@@ -1160,10 +1160,4 @@ crewai run
 
 يكتشف هذا الأمر تلقائيًا ما إذا كان مشروعك تدفقًا (بناءً على إعداد `type = "flow"` في pyproject.toml الخاص بك) ويشغّله وفقًا لذلك. هذه هي الطريقة الموصى بها لتشغيل التدفقات من سطر الأوامر.
 
-للتوافق مع الإصدارات السابقة، يمكنك أيضًا استخدام:
-
-```shell
-crewai flow kickoff
-```
-
-ومع ذلك، فإن أمر `crewai run` هو الطريقة المفضلة الآن لأنه يعمل لكل من فرق Crew والتدفقات.
+أمر `crewai flow kickoff` القديم deprecated. استخدم `crewai run` لكل من فرق Crew والتدفقات.

docs/edge/ar/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,82 @@
+---
+title: بطاقة واحدة لكل خطوة
+description: "كل خطوة على لوحة Studio هي بطاقة واحدة تجمع بين المهمة والوكيل الذي ينفّذها."
+icon: "layer-group"
+mode: "wide"
+---
+
+## نظرة عامة
+
+على لوحة Studio، تُمثَّل كل خطوة عمل بـ **بطاقة واحدة**. تجمع البطاقة بين عنصرين كانا في السابق في عُقد منفصلة:
+
+- **المهمة** — ماذا تفعل (الاسم، الوصف، المخرجات المتوقعة، وتنسيق الاستجابة).
+- **الوكيل** — من ينفّذها (الوكيل المُعيَّن ونموذجه وأدواته).
+
+الوكيل ليس مشاركًا مستقلاً في سير العمل لديك — بل هو سمة من سمات المهمة: *أي وكيل ينفّذ هذا العمل.* وضع المهمة والوكيل في بطاقة واحدة يجعل هذه العلاقة واضحة، ويحوّل أتمتتك إلى سلسلة واحدة من وحدات العمل من اليسار إلى اليمين يسهل قراءتها بنظرة واحدة.
+
+<Frame caption="بطاقة واحدة لكل خطوة: المهمة مع ملخص للوكيل المُعيَّن في التذييل.">
+  ![بطاقات الخطوات الموحّدة على اللوحة](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## على اللوحة
+
+تعرض كل بطاقة مطوية ما يلي:
+
+- **اسم المهمة ووصفها** في الأعلى.
+- **تذييل يلخّص الوكيل المُعيَّن** — الصورة الرمزية والاسم والنموذج والأدوات.
+
+لا توجد عقدة وكيل منفصلة ولا حافة عمودية من الوكيل ← المهمة. تتصل خطواتك مباشرةً ببعضها البعض بالترتيب الذي تُنفَّذ به.
+
+## في المحرّر
+
+افتح بطاقة لتحريرها. العرض الموسّع هو البطاقة نفسها في حالة مفصّلة — وليس شاشة مختلفة — منظّمة في قسمين موسومين بوضوح.
+
+<Frame caption="المحرّر الموسّع: قسم المهمة مفتوح، والوكيل ملخّص أسفله.">
+  ![محرّر الخطوة الموسّع](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### المهمة — ماذا تفعل
+
+مفتوحة افتراضيًا، لأنها ما تحرّره عادةً:
+
+- **الاسم**
+- **الوصف**
+- **المخرجات المتوقعة**
+- **تنسيق الاستجابة** — يظهر هنا لأنه يتحكم تحديدًا في ما تقرأه الخطوات اللاحقة (مثل التوجيه) من هذه الخطوة.
+
+### الوكيل — من ينفّذها
+
+يُعرض الوكيل المُعيَّن كملخّص — **الاسم والنموذج والأدوات في سطر واحد**. ويُحفَظ إعداده الأعمق خلف قسمين قابلين للطي:
+
+- **الدور والهدف والخلفية**
+- **إعدادات الوكيل** — الاستدلال، الحد الأقصى لمحاولات الاستدلال، السماح بالتفويض، الحد الأقصى للتكرارات، وإعدادات LLM.
+
+<Tip>
+  الإعداد الكامل للوكيل — الدور، الهدف، الخلفية، النموذج، الأدوات، إعدادات LLM، وكامل كتلة إعدادات الوكيل — موجود خلف القسمين القابلين للطي **الدور والهدف والخلفية** و**إعدادات الوكيل**، منظّمًا حسب عدد مرّات تحريرك له.
+</Tip>
+
+## التبديل مقابل تحرير الوكيل
+
+هناك طريقتان متمايزتان للتعامل مع الوكيل في البطاقة، وكل منهما تؤدي وظيفة مختلفة:
+
+- **التبديل (Swap)** يعيد تعيين *أي* وكيل ينفّذ هذه المهمة. استخدم عنصر التحكم **تبديل** لاختيار وكيل مختلف من هذا المشروع، أو اختيار واحد من مستودع الوكلاء، أو إنشاء وكيل جديد. هذا مقصور على نطاق المهمة.
+- **تحرير** الوكيل — بفتح **الدور والهدف والخلفية** أو **إعدادات الوكيل** — يغيّر الوكيل *نفسه*.
+
+<Frame caption="التبديل يغيّر الوكيل الذي ينفّذ المهمة.">
+  ![لوحة تبديل الوكيل](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **الوكلاء قابلون لإعادة الاستخدام ومشتركون.** يمكن للوكيل نفسه تنفيذ أكثر من مهمة عبر مشروعك. تحرير دور الوكيل أو خلفيته أو إعداداته يحدّث ذلك الوكيل **في كل مكان يُستخدم فيه** — وليس فقط في البطاقة التي فتحتها. إذا أردت تطبيق تغيير على خطوة واحدة فقط، فقم **بالتبديل** إلى وكيل مختلف بدلاً من تحرير الوكيل المشترك.
+</Warning>
+
+## ذات صلة
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/ar/enterprise/features/crew-studio" icon="pencil">
+    أنشئ الأتمتة بمساعدة الذكاء الاصطناعي ومحرّر مرئي.
+  </Card>
+  <Card title="مستودعات الوكلاء" href="/ar/enterprise/features/agent-repositories" icon="users">
+    إدارة الوكلاء وإعادة استخدامهم عبر أتمتتك.
+  </Card>
+</CardGroup>

docs/edge/ar/guides/flows/first-flow.mdx

@@ -172,7 +172,7 @@ crewai install
 ## الخطوة 8: تشغيل Flow
 
 ```bash
-crewai flow kickoff
+crewai run
 ```
 
 عند تشغيل هذا الأمر، ستشاهد Flow يعمل:

docs/edge/en/changelog.mdx

@@ -4,6 +4,83 @@ description: "Product updates, improvements, and bug fixes for CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="Jun 24, 2026">
+  ## v1.14.8a5
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a5)
+
+  ## What's Changed
+
+  ### Features
+  - Make declarative refs work across flows and crews (#6326)
+
+  ### Bug Fixes
+  - Fix JSON schema flow state kickoff inputs (#6325)
+
+  ### Documentation
+  - Nest One Card per Step under Crew Studio and drop rollout banner (AGE-107) (#6317)
+  - Update snapshot and changelog for v1.14.8a4 (#6319)
+
+  ### Refactoring
+  - Remove `StateProxy` from flow state access (#6327)
+
+  ## Contributors
+
+  @jessemiller, @vinibrsl
+
+</Update>
+
+<Update label="Jun 24, 2026">
+  ## v1.14.8a4
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a4)
+
+  ## What's Changed
+
+  ### Features
+  - Support conversational flows in the CLI TUI.
+
+  ### Bug Fixes
+  - Fix symlink path traversal in skill archive extraction.
+  - Validate declarative flow definition paths.
+
+  ### Documentation
+  - Update snapshot and changelog for v1.14.8a3.
+
+  ## Contributors
+
+  @lorenzejay, @theCyberTech, @vinibrsl
+
+</Update>
+
+<Update label="Jun 23, 2026">
+  ## v1.14.8a3
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a3)
+
+  ## What's Changed
+
+  ### Features
+  - Add unified declarative flow loading
+  - Improve crewai run startup UX
+  - Consolidate `crewai run` and `crewai flow kickoff`
+  - Keep flow method progress visible for nested crews
+  - Add declarative Flow CLI support
+  - Allow `@router()` as start method of a flow
+  - Add typed output schemas for CrewAI tools
+
+  ### Bug Fixes
+  - Pin opentelemetry to ~=1.42.0
+
+  ### Documentation
+  - Add "One Card per Step" Studio page
+
+  ## Contributors
+
+  @jessemiller, @joaomdmoura, @lucasgomide, @vinibrsl
+
+</Update>
+
 <Update label="Jun 18, 2026">
   ## v1.14.8a2
 
@@ -64,7 +141,7 @@ mode: "wide"
   - Implement Flow definition run tools without Python code
   - Drive human feedback from the flow definition
   - Wire config and persistence from FlowDefinition into the runtime
-  - Add experimental `crewai run --definition` for flows
+  - Add `crewai run --definition` for declarative flows
   - Support ZIP deployment fallback and JSON crew project env runs
   - Introduce JSON first crews
 

docs/edge/en/concepts/flows.mdx

@@ -956,13 +956,13 @@ Once all of the dependencies are installed, you need to activate the virtual env
 source .venv/bin/activate
 ```
 
-After activating the virtual environment, you can run the flow by executing one of the following commands:
+After activating the virtual environment, you can run the flow with the CrewAI CLI:
 
 ```bash
-crewai flow kickoff
+crewai run
 ```
 
-or
+You can also run the project script directly:
 
 ```bash
 uv run kickoff
@@ -1160,10 +1160,4 @@ crewai run
 
 This command automatically detects if your project is a flow (based on the `type = "flow"` setting in your pyproject.toml) and runs it accordingly. This is the recommended way to run flows from the command line.
 
-For backward compatibility, you can also use:
-
-```shell
-crewai flow kickoff
-```
-
-However, the `crewai run` command is now the preferred method as it works for both crews and flows.
+The legacy `crewai flow kickoff` command is deprecated. Use `crewai run` for both crews and flows.

docs/edge/en/concepts/tools.mdx

@@ -39,6 +39,7 @@ The Enterprise Tools Repository includes:
 - **Error Handling**: Incorporates robust error handling mechanisms to ensure smooth operation.
 - **Caching Mechanism**: Features intelligent caching to optimize performance and reduce redundant operations.
 - **Asynchronous Support**: Handles both synchronous and asynchronous tools, enabling non-blocking operations.
+- **Typed Outputs**: Uses optional Pydantic models to give agents clear JSON fields while direct Python calls still receive the tool's normal return value.
 
 ## Using CrewAI Tools
 
@@ -184,6 +185,55 @@ class MyCustomTool(BaseTool):
         return "Tool's result"
 ```
 
+### Typed Tool Outputs
+
+When a tool returns structured data, define a Pydantic output model. This gives the agent field names it can trust, such as `sku`, `quantity`, or `needs_reorder`.
+
+Direct Python calls still receive the value your tool returns. When an agent uses the tool, CrewAI sends the agent a JSON string based on the output model.
+
+```python Code
+from crewai.tools import BaseTool
+from pydantic import BaseModel
+
+class InventoryResult(BaseModel):
+    sku: str
+    quantity: int
+    needs_reorder: bool
+
+class InventoryTool(BaseTool):
+    name: str = "Inventory Check"
+    description: str = "Checks current stock for a product SKU."
+
+    def _run(self, sku: str) -> InventoryResult:
+        quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)
+        return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)
+
+tool = InventoryTool()
+
+# Direct calls receive the raw Pydantic object.
+result = tool.run(sku="SKU-123")
+print(result.quantity)
+```
+
+To send Markdown or another short text format to the agent, override `format_output_for_agent`. Direct calls to `tool.run(...)` still return the normal Python value.
+
+```python Code
+class InventoryTool(BaseTool):
+    name: str = "Inventory Check"
+    description: str = "Checks current stock for a product SKU."
+
+    def _run(self, sku: str) -> InventoryResult:
+        quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)
+        return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)
+
+    def format_output_for_agent(self, raw_result: object) -> str:
+        result = InventoryResult.model_validate(raw_result)
+        status = "reorder needed" if result.needs_reorder else "stock is healthy"
+        return f"{result.sku}: {result.quantity} units. {status}."
+```
+
+If you do not override `format_output_for_agent`, typed outputs are sent to the agent as JSON. Plain string results work as before.
+
 ## Asynchronous Tool Support
 
 CrewAI supports asynchronous tools, allowing you to implement tools that perform non-blocking operations like network requests, file I/O, or other async operations without blocking the main execution thread.

docs/edge/en/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,82 @@
+---
+title: One Card per Step
+description: "Each step on the Studio canvas is a single card that combines the task and the agent that performs it."
+icon: "layer-group"
+mode: "wide"
+---
+
+## Overview
+
+On the Studio canvas, each step of work is represented by a **single card**. The card combines two things that used to live in separate nodes:
+
+- **The task** — what to do (name, description, expected output, and response format).
+- **The agent** — who does it (the assigned agent, its model, and its tools).
+
+An agent isn't an independent participant in your workflow — it's an attribute of the task: *which agent performs this work.* Putting the task and its agent on one card makes that relationship explicit and turns your automation into a single, left-to-right chain of work units that's easier to read at a glance.
+
+<Frame caption="One card per step: the task with its assigned agent summarized in the footer.">
+  ![Merged step cards on the canvas](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## On the canvas
+
+Each collapsed card shows:
+
+- The **task name and description** at the top.
+- A **footer summarizing the assigned agent** — avatar, name, model, and tools.
+
+There's no separate agent node and no vertical agent → task edge. Your steps connect directly to one another in the order they run.
+
+## In the editor
+
+Open a card to edit it. The expanded view is the same card in a detailed state — not a different screen — organized into two clearly labeled sections.
+
+<Frame caption="The expanded editor: the task section open, the agent summarized below it.">
+  ![Expanded step editor](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### The task — what to do
+
+Open by default, since this is what you usually edit:
+
+- **Name**
+- **Description**
+- **Expected Output**
+- **Response Format** — surfaced here because it controls exactly what downstream steps (such as routing) read from this step.
+
+### The agent — who does it
+
+The assigned agent is shown as a summary — **name, model, and tools inline**. Its deeper configuration is preserved behind two disclosures:
+
+- **Role, goal & backstory**
+- **Agent settings** — reasoning, max reasoning attempts, allow delegation, max iterations, and LLM settings.
+
+<Tip>
+  An agent's full configuration — Role, Goal, Backstory, Model, Tools, LLM Settings, and the complete Agent Settings block — lives behind the **Role, goal & backstory** and **Agent settings** disclosures, organized by how often you edit it.
+</Tip>
+
+## Swapping vs. editing the agent
+
+There are two distinct ways to work with the agent on a card, and they do different things:
+
+- **Swap** reassigns *which* agent performs this task. Use the **Swap** control to pick a different agent from this project, choose one from your Agent Repository, or create a new agent. This is scoped to the task.
+- **Editing** the agent — opening **Role, goal & backstory** or **Agent settings** — changes the agent *itself*.
+
+<Frame caption="Swap changes which agent performs the task.">
+  ![Swap agent panel](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **Agents are reusable and shared.** The same agent can perform more than one task across your project. Editing an agent's role, backstory, or settings updates that agent **everywhere it's used** — not just on the card you opened. If you want a change to apply to only one step, **Swap** in a different agent instead of editing the shared one.
+</Warning>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/en/enterprise/features/crew-studio" icon="pencil">
+    Build automations with AI assistance and a visual editor.
+  </Card>
+  <Card title="Agent Repositories" href="/en/enterprise/features/agent-repositories" icon="users">
+    Manage and reuse agents across your automations.
+  </Card>
+</CardGroup>

docs/edge/en/guides/flows/first-flow.mdx

@@ -395,7 +395,7 @@ crewai install
 Now it's time to see your flow in action! Run it using the CrewAI CLI:
 
 ```bash
-crewai flow kickoff
+crewai run
 ```
 
 When you run this command, you'll see your flow spring to life:

docs/edge/en/guides/tools/publish-custom-tools.mdx

@@ -65,7 +65,7 @@ Regardless of which approach you use, your tool must:
 - Have a **`description`** — tells the agent when and how to use the tool. This directly affects how well agents use your tool, so be clear and specific.
 - Implement **`_run`** (BaseTool) or provide a **function body** (@tool) — the synchronous execution logic.
 - Use **type annotations** on all parameters and return values.
-- Return a **string** result (or something that can be meaningfully converted to one).
+- Return a **string** result, or define an optional Pydantic output schema for structured results.
 
 ### Optional: Async Support
 
@@ -104,6 +104,67 @@ class TranslateInput(BaseModel):
 
 Explicit schemas are recommended for published tools — they produce better agent behavior and clearer documentation for your users.
 
+### Optional: Typed Outputs with `result_schema`
+
+If your tool returns structured data, define a Pydantic output model. This is a good default for published tools because users and agents can rely on named fields.
+
+Direct Python calls still receive the value your tool returns. When an agent uses the tool, CrewAI sends the agent JSON based on the output model.
+
+CrewAI can infer the output schema from a Pydantic return annotation:
+
+```python
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+
+class GeolocateResult(BaseModel):
+    latitude: float = Field(..., description="Latitude in decimal degrees.")
+    longitude: float = Field(..., description="Longitude in decimal degrees.")
+
+
+class GeolocateTool(BaseTool):
+    name: str = "Geolocate"
+    description: str = "Converts a street address into latitude/longitude coordinates."
+
+    def _run(self, address: str) -> GeolocateResult:
+        if "1600 Pennsylvania" in address:
+            return GeolocateResult(latitude=38.8977, longitude=-77.0365)
+        return GeolocateResult(latitude=40.7128, longitude=-74.0060)
+```
+
+Set `result_schema` explicitly when your tool returns a dictionary:
+
+```python
+class GeolocateTool(BaseTool):
+    name: str = "Geolocate"
+    description: str = "Converts a street address into latitude/longitude coordinates."
+    result_schema: type[BaseModel] = GeolocateResult
+
+    def _run(self, address: str) -> dict[str, float]:
+        if "1600 Pennsylvania" in address:
+            return {"latitude": 38.8977, "longitude": -77.0365}
+        return {"latitude": 40.7128, "longitude": -74.0060}
+```
+
+If agents should receive a short text summary instead of JSON, override `format_output_for_agent` on your `BaseTool` subclass.
+
+```python
+class GeolocateTool(BaseTool):
+    name: str = "Geolocate"
+    description: str = "Converts a street address into latitude/longitude coordinates."
+
+    def _run(self, address: str) -> GeolocateResult:
+        if "1600 Pennsylvania" in address:
+            return GeolocateResult(latitude=38.8977, longitude=-77.0365)
+        return GeolocateResult(latitude=40.7128, longitude=-74.0060)
+
+    def format_output_for_agent(self, raw_result: object) -> str:
+        result = GeolocateResult.model_validate(raw_result)
+        return f"Latitude {result.latitude}, longitude {result.longitude}"
+```
+
+The override only changes what the agent sees. Direct users of your package still receive the normal value from `tool.run(...)`.
+
 ### Optional: Environment Variables
 
 If your tool requires API keys or other configuration, declare them with `env_vars` so users know what to set:
@@ -241,4 +302,4 @@ agent = Agent(
     tools=[GeolocateTool()],
     # ...
 )
-```
+```

docs/edge/en/learn/create-custom-tools.mdx

@@ -53,6 +53,111 @@ def my_simple_tool(question: str) -> str:
     return "Tool output"
 ```
 
+### Best Practice: Define Typed Outputs
+
+When a tool returns structured data, define a Pydantic output model. This helps the agent read the result as clear fields instead of guessing from plain text.
+
+Typed outputs are useful for results with stable fields, such as IDs, status values, scores, prices, or lists. Plain strings are still fine for short prose results.
+
+Direct Python calls still receive the value your tool returns. When an agent uses a typed tool, CrewAI sends the agent JSON based on the output model.
+
+#### Return a Pydantic Model
+
+CrewAI infers the output schema when your `BaseTool` has a Pydantic return annotation.
+
+```python Code
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+class InventoryResult(BaseModel):
+    sku: str = Field(description="The product SKU.")
+    quantity: int = Field(description="Units available.")
+    needs_reorder: bool = Field(description="Whether the item should be reordered.")
+
+class InventoryTool(BaseTool):
+    name: str = "Inventory Check"
+    description: str = "Check current stock for a product SKU."
+
+    def _run(self, sku: str) -> InventoryResult:
+        quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)
+        return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)
+
+tool = InventoryTool()
+result = tool.run(sku="SKU-123")
+
+# Direct Python calls receive the raw Pydantic object.
+print(result.quantity)
+```
+
+When an agent calls `InventoryTool`, it receives JSON like this:
+
+```json
+{"sku":"SKU-123","quantity":14,"needs_reorder":false}
+```
+
+#### Use `result_schema` with Dictionary Results
+
+If your tool returns a dictionary, set `result_schema` explicitly. You can do this on a `BaseTool` subclass or with the `@tool` decorator:
+
+```python Code
+from crewai.tools import tool
+from pydantic import BaseModel, Field
+
+class ProductResult(BaseModel):
+    sku: str = Field(description="The product SKU.")
+    name: str = Field(description="The product name.")
+    in_stock: bool = Field(description="Whether the product is available.")
+
+@tool("Product Lookup", result_schema=ProductResult)
+def product_lookup(sku: str) -> dict[str, object]:
+    """Look up product availability by SKU."""
+    catalog = {
+        "SKU-123": ("Noise-canceling headset", True),
+        "SKU-456": ("USB-C dock", False),
+    }
+    name, in_stock = catalog.get(sku, ("Unknown product", False))
+    return {
+        "sku": sku,
+        "name": name,
+        "in_stock": in_stock,
+    }
+```
+
+#### Customize the Text Sent to the Agent
+
+By default, typed tool outputs are sent to the agent as JSON. If the agent should receive a short summary instead, subclass `BaseTool` and override `format_output_for_agent`.
+
+```python Code
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+class InventoryResult(BaseModel):
+    sku: str = Field(description="The product SKU.")
+    quantity: int = Field(description="Units available.")
+    needs_reorder: bool = Field(description="Whether the item should be reordered.")
+
+class InventoryTool(BaseTool):
+    name: str = "Inventory Check"
+    description: str = "Check current stock for a product SKU."
+
+    def _run(self, sku: str) -> InventoryResult:
+        quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)
+        return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)
+
+    def format_output_for_agent(self, raw_result: object) -> str:
+        result = InventoryResult.model_validate(raw_result)
+        status = "reorder needed" if result.needs_reorder else "stock is healthy"
+        return f"{result.sku}: {result.quantity} units. {status}."
+
+tool = InventoryTool()
+result = tool.run(sku="SKU-123")
+
+# Direct Python calls receive the raw Pydantic object.
+print(result.quantity)
+```
+
+The override only changes what the agent sees. Direct calls to `tool.run(...)` still return the normal Python value.
+
 ### Defining a Cache Function for the Tool
 
 To optimize tool performance with caching, define custom caching strategies using the `cache_function` attribute.

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

@@ -195,9 +195,12 @@ class ToolCallHookContext:
     agent: Agent | None          # Agent executing
     task: Task | None            # Current task
     crew: Crew | None            # Crew instance
-    tool_result: str | None      # Tool result (after hooks)
+    tool_result: str | None      # Agent-facing result string (after hooks)
+    raw_tool_result: Any | None  # Raw Python result (after hooks)
 ```
 
+For typed tool outputs, `tool_result` is the string the agent sees. By default, this is JSON. If the tool uses custom formatting, it can be Markdown or another string. `raw_tool_result` is the original Python value returned by the tool.
+
 ## Common Patterns
 
 ### Safety and Validation

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

@@ -60,9 +60,12 @@ class ToolCallHookContext:
     agent: Agent | BaseAgent | None   # Agent executing the tool
     task: Task | None                 # Current task
     crew: Crew | None                 # Crew instance
-    tool_result: str | None           # Tool result (after hooks only)
+    tool_result: str | None           # Agent-facing result string (after hooks only)
+    raw_tool_result: Any | None       # Raw Python result (after hooks only)
 ```
 
+For typed tool outputs, `tool_result` is the string the agent sees. By default, this is JSON. If the tool uses custom formatting, it can be Markdown or another string. Use `raw_tool_result` when your hook needs the typed object or dictionary.
+
 ### Modifying Tool Inputs
 
 **Important:** Always modify tool inputs in-place:

docs/edge/ko/changelog.mdx

@@ -4,6 +4,83 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="2026년 6월 24일">
+  ## v1.14.8a5
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a5)
+
+  ## 변경 사항
+
+  ### 기능
+  - 선언적 참조가 흐름과 크루 간에 작동하도록 수정 (#6326)
+
+  ### 버그 수정
+  - JSON 스키마 흐름 상태 시작 입력 수정 (#6325)
+
+  ### 문서
+  - Crew Studio 아래에 단계별 One Card를 중첩하고 롤아웃 배너 제거 (AGE-107) (#6317)
+  - v1.14.8a4의 스냅샷 및 변경 로그 업데이트 (#6319)
+
+  ### 리팩토링
+  - 흐름 상태 접근에서 `StateProxy` 제거 (#6327)
+
+  ## 기여자
+
+  @jessemiller, @vinibrsl
+
+</Update>
+
+<Update label="2026년 6월 24일">
+  ## v1.14.8a4
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a4)
+
+  ## 변경 사항
+
+  ### 기능
+  - CLI TUI에서 대화형 흐름 지원.
+
+  ### 버그 수정
+  - 기술 아카이브 추출 시 심볼릭 링크 경로 탐색 문제 수정.
+  - 선언적 흐름 정의 경로 검증.
+
+  ### 문서
+  - v1.14.8a3에 대한 스냅샷 및 변경 로그 업데이트.
+
+  ## 기여자
+
+  @lorenzejay, @theCyberTech, @vinibrsl
+
+</Update>
+
+<Update label="2026년 6월 23일">
+  ## v1.14.8a3
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a3)
+
+  ## 변경 사항
+
+  ### 기능
+  - 통합 선언적 흐름 로딩 추가
+  - crewai run 시작 UX 개선
+  - `crewai run`과 `crewai flow kickoff` 통합
+  - 중첩된 크루의 흐름 메서드 진행 상황 표시 유지
+  - 선언적 Flow CLI 지원 추가
+  - 흐름의 시작 메서드로 `@router()` 허용
+  - CrewAI 도구에 대한 타입이 지정된 출력 스키마 추가
+
+  ### 버그 수정
+  - opentelemetry를 ~=1.42.0으로 고정
+
+  ### 문서
+  - "단계당 한 카드" 스튜디오 페이지 추가
+
+  ## 기여자
+
+  @jessemiller, @joaomdmoura, @lucasgomide, @vinibrsl
+
+</Update>
+
 <Update label="2026년 6월 18일">
   ## v1.14.8a2
 
@@ -64,7 +141,7 @@ mode: "wide"
   - Python 코드 없이 Flow 정의 실행 도구 구현
   - Flow 정의에서 인간 피드백 유도
   - FlowDefinition의 구성 및 지속성을 런타임에 연결
-  - 흐름을 위한 실험적 `crewai run --definition` 추가
+  - 선언적 흐름을 위한 `crewai run --definition` 추가
   - ZIP 배포 대체 및 JSON 크루 프로젝트 환경 실행 지원
   - JSON 우선 크루 도입
 

docs/edge/ko/concepts/flows.mdx

@@ -951,7 +951,7 @@ source .venv/bin/activate
 가상 환경을 활성화한 후, 아래 명령어 중 하나를 실행하여 플로우를 실행할 수 있습니다:
 
 ```bash
-crewai flow kickoff
+crewai run
 ```
 
 또는
@@ -1054,10 +1054,4 @@ crewai run
 
 이 명령어는 프로젝트가 pyproject.toml의 `type = "flow"` 설정을 기반으로 flow인지 자동으로 감지하여 해당 방식으로 실행합니다. 명령줄에서 flow를 실행하는 권장 방법입니다.
 
-하위 호환성을 위해 다음 명령어도 사용할 수 있습니다:
-
-```shell
-crewai flow kickoff
-```
-
-하지만 `crewai run` 명령어가 이제 crew와 flow 모두에 작동하므로 더욱 선호되는 방법입니다.
+레거시 `crewai flow kickoff` 명령어는 deprecated되었습니다. crew와 flow 모두 `crewai run`을 사용하세요.

docs/edge/ko/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,82 @@
+---
+title: 단계당 하나의 카드
+description: "Studio 캔버스의 각 단계는 작업과 이를 수행하는 에이전트를 하나로 결합한 단일 카드입니다."
+icon: "layer-group"
+mode: "wide"
+---
+
+## 개요
+
+Studio 캔버스에서 각 작업 단계는 **하나의 카드**로 표현됩니다. 이 카드는 이전에 별도의 노드에 있던 두 가지를 결합합니다:
+
+- **작업(Task)** — 무엇을 할지(이름, 설명, 예상 출력, 응답 형식).
+- **에이전트(Agent)** — 누가 수행하는지(할당된 에이전트, 모델, 도구).
+
+에이전트는 워크플로의 독립적인 참여자가 아니라 작업의 속성, 즉 *이 작업을 어떤 에이전트가 수행하는지*를 나타냅니다. 작업과 에이전트를 하나의 카드에 두면 이 관계가 명확해지고, 자동화가 왼쪽에서 오른쪽으로 이어지는 단일 작업 단위 체인이 되어 한눈에 읽기 쉬워집니다.
+
+<Frame caption="단계당 하나의 카드: 작업과 푸터에 요약된 할당 에이전트.">
+  ![캔버스의 통합 단계 카드](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## 캔버스에서
+
+접힌 각 카드는 다음을 표시합니다:
+
+- 상단의 **작업 이름과 설명**.
+- **할당된 에이전트를 요약한 푸터** — 아바타, 이름, 모델, 도구.
+
+별도의 에이전트 노드나 에이전트 → 작업 세로 연결선이 없습니다. 각 단계는 실행 순서대로 서로 직접 연결됩니다.
+
+## 에디터에서
+
+카드를 열어 편집합니다. 확장된 보기는 다른 화면이 아니라 동일한 카드의 상세 상태이며, 명확하게 구분된 두 개의 섹션으로 구성됩니다.
+
+<Frame caption="확장된 에디터: 작업 섹션이 열려 있고 그 아래에 에이전트가 요약되어 있습니다.">
+  ![확장된 단계 에디터](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### 작업 — 무엇을 할지
+
+가장 자주 편집하는 항목이므로 기본적으로 열려 있습니다:
+
+- **이름**
+- **설명**
+- **예상 출력**
+- **응답 형식** — 다운스트림 단계(예: 라우팅)가 이 단계에서 무엇을 읽을지 정확히 제어하므로 여기에 표시됩니다.
+
+### 에이전트 — 누가 수행하는지
+
+할당된 에이전트는 요약으로 표시됩니다 — **이름, 모델, 도구가 인라인으로** 표시됩니다. 더 깊은 구성은 두 개의 접이식 섹션 뒤에 보존됩니다:
+
+- **역할, 목표 및 배경 스토리**
+- **에이전트 설정** — 추론, 최대 추론 시도 횟수, 위임 허용, 최대 반복 횟수, LLM 설정.
+
+<Tip>
+  에이전트의 전체 구성 — 역할, 목표, 배경 스토리, 모델, 도구, LLM 설정 및 전체 에이전트 설정 블록 — 은 **역할, 목표 및 배경 스토리**와 **에이전트 설정** 접이식 섹션 뒤에 편집 빈도에 따라 정리되어 있습니다.
+</Tip>
+
+## 에이전트 교체 vs. 편집
+
+카드에서 에이전트를 다루는 방식은 두 가지로 구분되며, 각각 다른 작업을 수행합니다:
+
+- **교체(Swap)** 는 *어떤* 에이전트가 이 작업을 수행할지 재할당합니다. **교체** 컨트롤을 사용하여 이 프로젝트의 다른 에이전트를 선택하거나, 에이전트 저장소에서 선택하거나, 새 에이전트를 만들 수 있습니다. 이는 작업 범위로 한정됩니다.
+- 에이전트 **편집** — **역할, 목표 및 배경 스토리** 또는 **에이전트 설정** 을 여는 것 — 은 에이전트 *자체*를 변경합니다.
+
+<Frame caption="교체는 작업을 수행할 에이전트를 변경합니다.">
+  ![에이전트 교체 패널](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **에이전트는 재사용 가능하며 공유됩니다.** 동일한 에이전트가 프로젝트 전반에서 둘 이상의 작업을 수행할 수 있습니다. 에이전트의 역할, 배경 스토리 또는 설정을 편집하면 열어 본 카드뿐만 아니라 **해당 에이전트가 사용되는 모든 곳**에서 업데이트됩니다. 변경 사항을 하나의 단계에만 적용하려면 공유 에이전트를 편집하지 말고 다른 에이전트로 **교체**하세요.
+</Warning>
+
+## 관련 항목
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/ko/enterprise/features/crew-studio" icon="pencil">
+    AI 지원과 비주얼 에디터로 자동화를 구축합니다.
+  </Card>
+  <Card title="에이전트 저장소" href="/ko/enterprise/features/agent-repositories" icon="users">
+    자동화 전반에서 에이전트를 관리하고 재사용합니다.
+  </Card>
+</CardGroup>

docs/edge/ko/guides/flows/first-flow.mdx

@@ -393,7 +393,7 @@ crewai install
 이제 여러분의 flow가 실제로 작동하는 모습을 볼 차례입니다! CrewAI CLI를 사용하여 flow를 실행하세요:
 
 ```bash
-crewai flow kickoff
+crewai run
 ```
 
 이 명령어를 실행하면 flow가 다음과 같이 작동하는 것을 확인할 수 있습니다:

docs/edge/pt-BR/changelog.mdx

@@ -4,6 +4,83 @@ description: "Atualizações de produto, melhorias e correções do CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="24 jun 2026">
+  ## v1.14.8a5
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a5)
+
+  ## O que mudou
+
+  ### Recursos
+  - Fazer referências declarativas funcionarem em diferentes fluxos e equipes (#6326)
+
+  ### Correções de Bugs
+  - Corrigir entradas de kickoff de estado de fluxo do esquema JSON (#6325)
+
+  ### Documentação
+  - Aninhar One Card por Etapa sob Crew Studio e remover banner de rollout (AGE-107) (#6317)
+  - Atualizar snapshot e changelog para v1.14.8a4 (#6319)
+
+  ### Refatoração
+  - Remover `StateProxy` do acesso ao estado de fluxo (#6327)
+
+  ## Contribuidores
+
+  @jessemiller, @vinibrsl
+
+</Update>
+
+<Update label="24 jun 2026">
+  ## v1.14.8a4
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a4)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Suporte a fluxos de conversa na TUI do CLI.
+
+  ### Correções de Bugs
+  - Corrigir a travessia de caminho de symlink na extração de arquivo de habilidade.
+  - Validar os caminhos de definição de fluxo declarativo.
+
+  ### Documentação
+  - Atualizar snapshot e changelog para v1.14.8a3.
+
+  ## Contribuidores
+
+  @lorenzejay, @theCyberTech, @vinibrsl
+
+</Update>
+
+<Update label="23 jun 2026">
+  ## v1.14.8a3
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a3)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar carregamento de fluxo declarativo unificado
+  - Melhorar a experiência de inicialização do crewai run
+  - Consolidar `crewai run` e `crewai flow kickoff`
+  - Manter o progresso do método de fluxo visível para equipes aninhadas
+  - Adicionar suporte a Flow CLI declarativo
+  - Permitir `@router()` como método de início de um fluxo
+  - Adicionar esquemas de saída tipados para ferramentas CrewAI
+
+  ### Correções de Bugs
+  - Fixar opentelemetry em ~=1.42.0
+
+  ### Documentação
+  - Adicionar página "Uma Cartão por Etapa" no Studio
+
+  ## Contribuidores
+
+  @jessemiller, @joaomdmoura, @lucasgomide, @vinibrsl
+
+</Update>
+
 <Update label="18 jun 2026">
   ## v1.14.8a2
 
@@ -64,7 +141,7 @@ mode: "wide"
   - Implementar ferramentas de execução de definição de fluxo sem código Python
   - Conduzir feedback humano a partir da definição de fluxo
   - Conectar configuração e persistência do FlowDefinition ao tempo de execução
-  - Adicionar `crewai run --definition` experimental para fluxos
+  - Adicionar `crewai run --definition` para fluxos declarativos
   - Suportar fallback de implantação ZIP e execuções de projeto de equipe em JSON
   - Introduzir equipes em JSON primeiro
 

docs/edge/pt-BR/concepts/flows.mdx

@@ -948,7 +948,7 @@ source .venv/bin/activate
 Com o ambiente ativado, execute o flow usando um dos comandos:
 
 ```bash
-crewai flow kickoff
+crewai run
 ```
 
 ou
@@ -1052,10 +1052,4 @@ crewai run
 
 O comando detecta automaticamente se seu projeto é um flow (com base na configuração `type = "flow"` no pyproject.toml) e executa conforme o esperado. Esse é o método recomendado para executar flows pelo terminal.
 
-Por compatibilidade retroativa, também é possível usar:
-
-```shell
-crewai flow kickoff
-```
-
-No entanto, o comando `crewai run` é agora o preferido, pois funciona tanto para crews quanto para flows.
+O comando legado `crewai flow kickoff` está deprecated. Use `crewai run` para crews e flows.

docs/edge/pt-BR/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,82 @@
+---
+title: Um Card por Etapa
+description: "Cada etapa no canvas do Studio é um único card que combina a tarefa e o agente que a executa."
+icon: "layer-group"
+mode: "wide"
+---
+
+## Visão geral
+
+No canvas do Studio, cada etapa de trabalho é representada por um **único card**. O card combina dois elementos que antes ficavam em nós separados:
+
+- **A tarefa** — o que fazer (nome, descrição, saída esperada e formato da resposta).
+- **O agente** — quem faz (o agente atribuído, seu modelo e suas ferramentas).
+
+Um agente não é um participante independente do seu fluxo de trabalho — ele é um atributo da tarefa: *qual agente executa este trabalho.* Colocar a tarefa e seu agente em um único card torna essa relação explícita e transforma sua automação em uma única cadeia de unidades de trabalho, da esquerda para a direita, mais fácil de ler em uma olhada.
+
+<Frame caption="Um card por etapa: a tarefa com o agente atribuído resumido no rodapé.">
+  ![Cards de etapa unificados no canvas](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## No canvas
+
+Cada card recolhido mostra:
+
+- O **nome e a descrição da tarefa** no topo.
+- Um **rodapé resumindo o agente atribuído** — avatar, nome, modelo e ferramentas.
+
+Não há nó de agente separado nem aresta vertical de agente → tarefa. Suas etapas se conectam diretamente umas às outras na ordem em que são executadas.
+
+## No editor
+
+Abra um card para editá-lo. A visão expandida é o mesmo card em um estado detalhado — não uma tela diferente — organizada em duas seções claramente identificadas.
+
+<Frame caption="O editor expandido: a seção da tarefa aberta, com o agente resumido abaixo.">
+  ![Editor de etapa expandido](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### A tarefa — o que fazer
+
+Aberta por padrão, já que é o que você costuma editar:
+
+- **Nome**
+- **Descrição**
+- **Saída Esperada**
+- **Formato da Resposta** — exibido aqui porque controla exatamente o que as etapas seguintes (como o roteamento) leem desta etapa.
+
+### O agente — quem faz
+
+O agente atribuído é mostrado como um resumo — **nome, modelo e ferramentas em linha**. Sua configuração mais detalhada é preservada por trás de duas seções recolhíveis:
+
+- **Papel, objetivo e história**
+- **Configurações do agente** — raciocínio, máximo de tentativas de raciocínio, permitir delegação, máximo de iterações e configurações de LLM.
+
+<Tip>
+  A configuração completa de um agente — Papel, Objetivo, História, Modelo, Ferramentas, Configurações de LLM e todo o bloco de Configurações do agente — fica por trás das seções recolhíveis **Papel, objetivo e história** e **Configurações do agente**, organizada pela frequência com que você a edita.
+</Tip>
+
+## Trocar vs. editar o agente
+
+Há duas maneiras distintas de trabalhar com o agente em um card, e elas fazem coisas diferentes:
+
+- **Trocar** reatribui *qual* agente executa esta tarefa. Use o controle **Trocar** para escolher um agente diferente deste projeto, selecionar um do seu Repositório de Agentes ou criar um novo agente. Isso tem escopo limitado à tarefa.
+- **Editar** o agente — abrindo **Papel, objetivo e história** ou **Configurações do agente** — altera o agente *em si*.
+
+<Frame caption="Trocar muda qual agente executa a tarefa.">
+  ![Painel de troca de agente](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **Os agentes são reutilizáveis e compartilhados.** O mesmo agente pode executar mais de uma tarefa em todo o seu projeto. Editar o papel, a história ou as configurações de um agente atualiza esse agente **em todos os lugares onde ele é usado** — não apenas no card que você abriu. Se quiser que uma alteração se aplique a apenas uma etapa, **Troque** por um agente diferente em vez de editar o agente compartilhado.
+</Warning>
+
+## Relacionados
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/pt-BR/enterprise/features/crew-studio" icon="pencil">
+    Crie automações com assistência de IA e um editor visual.
+  </Card>
+  <Card title="Repositórios de Agentes" href="/pt-BR/enterprise/features/agent-repositories" icon="users">
+    Gerencie e reutilize agentes em suas automações.
+  </Card>
+</CardGroup>

docs/edge/pt-BR/guides/flows/first-flow.mdx

@@ -393,7 +393,7 @@ crewai install
 Agora é hora de ver seu flow em ação! Execute-o usando a CLI do CrewAI:
 
 ```bash
-crewai flow kickoff
+crewai run
 ```
 
 Quando você rodar esse comando, verá seu flow ganhando vida:

docs/v1.14.7/ar/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,82 @@
+---
+title: بطاقة واحدة لكل خطوة
+description: "كل خطوة على لوحة Studio هي بطاقة واحدة تجمع بين المهمة والوكيل الذي ينفّذها."
+icon: "layer-group"
+mode: "wide"
+---
+
+## نظرة عامة
+
+على لوحة Studio، تُمثَّل كل خطوة عمل بـ **بطاقة واحدة**. تجمع البطاقة بين عنصرين كانا في السابق في عُقد منفصلة:
+
+- **المهمة** — ماذا تفعل (الاسم، الوصف، المخرجات المتوقعة، وتنسيق الاستجابة).
+- **الوكيل** — من ينفّذها (الوكيل المُعيَّن ونموذجه وأدواته).
+
+الوكيل ليس مشاركًا مستقلاً في سير العمل لديك — بل هو سمة من سمات المهمة: *أي وكيل ينفّذ هذا العمل.* وضع المهمة والوكيل في بطاقة واحدة يجعل هذه العلاقة واضحة، ويحوّل أتمتتك إلى سلسلة واحدة من وحدات العمل من اليسار إلى اليمين يسهل قراءتها بنظرة واحدة.
+
+<Frame caption="بطاقة واحدة لكل خطوة: المهمة مع ملخص للوكيل المُعيَّن في التذييل.">
+  ![بطاقات الخطوات الموحّدة على اللوحة](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## على اللوحة
+
+تعرض كل بطاقة مطوية ما يلي:
+
+- **اسم المهمة ووصفها** في الأعلى.
+- **تذييل يلخّص الوكيل المُعيَّن** — الصورة الرمزية والاسم والنموذج والأدوات.
+
+لا توجد عقدة وكيل منفصلة ولا حافة عمودية من الوكيل ← المهمة. تتصل خطواتك مباشرةً ببعضها البعض بالترتيب الذي تُنفَّذ به.
+
+## في المحرّر
+
+افتح بطاقة لتحريرها. العرض الموسّع هو البطاقة نفسها في حالة مفصّلة — وليس شاشة مختلفة — منظّمة في قسمين موسومين بوضوح.
+
+<Frame caption="المحرّر الموسّع: قسم المهمة مفتوح، والوكيل ملخّص أسفله.">
+  ![محرّر الخطوة الموسّع](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### المهمة — ماذا تفعل
+
+مفتوحة افتراضيًا، لأنها ما تحرّره عادةً:
+
+- **الاسم**
+- **الوصف**
+- **المخرجات المتوقعة**
+- **تنسيق الاستجابة** — يظهر هنا لأنه يتحكم تحديدًا في ما تقرأه الخطوات اللاحقة (مثل التوجيه) من هذه الخطوة.
+
+### الوكيل — من ينفّذها
+
+يُعرض الوكيل المُعيَّن كملخّص — **الاسم والنموذج والأدوات في سطر واحد**. ويُحفَظ إعداده الأعمق خلف قسمين قابلين للطي:
+
+- **الدور والهدف والخلفية**
+- **إعدادات الوكيل** — الاستدلال، الحد الأقصى لمحاولات الاستدلال، السماح بالتفويض، الحد الأقصى للتكرارات، وإعدادات LLM.
+
+<Tip>
+  الإعداد الكامل للوكيل — الدور، الهدف، الخلفية، النموذج، الأدوات، إعدادات LLM، وكامل كتلة إعدادات الوكيل — موجود خلف القسمين القابلين للطي **الدور والهدف والخلفية** و**إعدادات الوكيل**، منظّمًا حسب عدد مرّات تحريرك له.
+</Tip>
+
+## التبديل مقابل تحرير الوكيل
+
+هناك طريقتان متمايزتان للتعامل مع الوكيل في البطاقة، وكل منهما تؤدي وظيفة مختلفة:
+
+- **التبديل (Swap)** يعيد تعيين *أي* وكيل ينفّذ هذه المهمة. استخدم عنصر التحكم **تبديل** لاختيار وكيل مختلف من هذا المشروع، أو اختيار واحد من مستودع الوكلاء، أو إنشاء وكيل جديد. هذا مقصور على نطاق المهمة.
+- **تحرير** الوكيل — بفتح **الدور والهدف والخلفية** أو **إعدادات الوكيل** — يغيّر الوكيل *نفسه*.
+
+<Frame caption="التبديل يغيّر الوكيل الذي ينفّذ المهمة.">
+  ![لوحة تبديل الوكيل](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **الوكلاء قابلون لإعادة الاستخدام ومشتركون.** يمكن للوكيل نفسه تنفيذ أكثر من مهمة عبر مشروعك. تحرير دور الوكيل أو خلفيته أو إعداداته يحدّث ذلك الوكيل **في كل مكان يُستخدم فيه** — وليس فقط في البطاقة التي فتحتها. إذا أردت تطبيق تغيير على خطوة واحدة فقط، فقم **بالتبديل** إلى وكيل مختلف بدلاً من تحرير الوكيل المشترك.
+</Warning>
+
+## ذات صلة
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/ar/enterprise/features/crew-studio" icon="pencil">
+    أنشئ الأتمتة بمساعدة الذكاء الاصطناعي ومحرّر مرئي.
+  </Card>
+  <Card title="مستودعات الوكلاء" href="/ar/enterprise/features/agent-repositories" icon="users">
+    إدارة الوكلاء وإعادة استخدامهم عبر أتمتتك.
+  </Card>
+</CardGroup>

docs/v1.14.7/en/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,82 @@
+---
+title: One Card per Step
+description: "Each step on the Studio canvas is a single card that combines the task and the agent that performs it."
+icon: "layer-group"
+mode: "wide"
+---
+
+## Overview
+
+On the Studio canvas, each step of work is represented by a **single card**. The card combines two things that used to live in separate nodes:
+
+- **The task** — what to do (name, description, expected output, and response format).
+- **The agent** — who does it (the assigned agent, its model, and its tools).
+
+An agent isn't an independent participant in your workflow — it's an attribute of the task: *which agent performs this work.* Putting the task and its agent on one card makes that relationship explicit and turns your automation into a single, left-to-right chain of work units that's easier to read at a glance.
+
+<Frame caption="One card per step: the task with its assigned agent summarized in the footer.">
+  ![Merged step cards on the canvas](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## On the canvas
+
+Each collapsed card shows:
+
+- The **task name and description** at the top.
+- A **footer summarizing the assigned agent** — avatar, name, model, and tools.
+
+There's no separate agent node and no vertical agent → task edge. Your steps connect directly to one another in the order they run.
+
+## In the editor
+
+Open a card to edit it. The expanded view is the same card in a detailed state — not a different screen — organized into two clearly labeled sections.
+
+<Frame caption="The expanded editor: the task section open, the agent summarized below it.">
+  ![Expanded step editor](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### The task — what to do
+
+Open by default, since this is what you usually edit:
+
+- **Name**
+- **Description**
+- **Expected Output**
+- **Response Format** — surfaced here because it controls exactly what downstream steps (such as routing) read from this step.
+
+### The agent — who does it
+
+The assigned agent is shown as a summary — **name, model, and tools inline**. Its deeper configuration is preserved behind two disclosures:
+
+- **Role, goal & backstory**
+- **Agent settings** — reasoning, max reasoning attempts, allow delegation, max iterations, and LLM settings.
+
+<Tip>
+  An agent's full configuration — Role, Goal, Backstory, Model, Tools, LLM Settings, and the complete Agent Settings block — lives behind the **Role, goal & backstory** and **Agent settings** disclosures, organized by how often you edit it.
+</Tip>
+
+## Swapping vs. editing the agent
+
+There are two distinct ways to work with the agent on a card, and they do different things:
+
+- **Swap** reassigns *which* agent performs this task. Use the **Swap** control to pick a different agent from this project, choose one from your Agent Repository, or create a new agent. This is scoped to the task.
+- **Editing** the agent — opening **Role, goal & backstory** or **Agent settings** — changes the agent *itself*.
+
+<Frame caption="Swap changes which agent performs the task.">
+  ![Swap agent panel](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **Agents are reusable and shared.** The same agent can perform more than one task across your project. Editing an agent's role, backstory, or settings updates that agent **everywhere it's used** — not just on the card you opened. If you want a change to apply to only one step, **Swap** in a different agent instead of editing the shared one.
+</Warning>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/en/enterprise/features/crew-studio" icon="pencil">
+    Build automations with AI assistance and a visual editor.
+  </Card>
+  <Card title="Agent Repositories" href="/en/enterprise/features/agent-repositories" icon="users">
+    Manage and reuse agents across your automations.
+  </Card>
+</CardGroup>

docs/v1.14.7/ko/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,82 @@
+---
+title: 단계당 하나의 카드
+description: "Studio 캔버스의 각 단계는 작업과 이를 수행하는 에이전트를 하나로 결합한 단일 카드입니다."
+icon: "layer-group"
+mode: "wide"
+---
+
+## 개요
+
+Studio 캔버스에서 각 작업 단계는 **하나의 카드**로 표현됩니다. 이 카드는 이전에 별도의 노드에 있던 두 가지를 결합합니다:
+
+- **작업(Task)** — 무엇을 할지(이름, 설명, 예상 출력, 응답 형식).
+- **에이전트(Agent)** — 누가 수행하는지(할당된 에이전트, 모델, 도구).
+
+에이전트는 워크플로의 독립적인 참여자가 아니라 작업의 속성, 즉 *이 작업을 어떤 에이전트가 수행하는지*를 나타냅니다. 작업과 에이전트를 하나의 카드에 두면 이 관계가 명확해지고, 자동화가 왼쪽에서 오른쪽으로 이어지는 단일 작업 단위 체인이 되어 한눈에 읽기 쉬워집니다.
+
+<Frame caption="단계당 하나의 카드: 작업과 푸터에 요약된 할당 에이전트.">
+  ![캔버스의 통합 단계 카드](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## 캔버스에서
+
+접힌 각 카드는 다음을 표시합니다:
+
+- 상단의 **작업 이름과 설명**.
+- **할당된 에이전트를 요약한 푸터** — 아바타, 이름, 모델, 도구.
+
+별도의 에이전트 노드나 에이전트 → 작업 세로 연결선이 없습니다. 각 단계는 실행 순서대로 서로 직접 연결됩니다.
+
+## 에디터에서
+
+카드를 열어 편집합니다. 확장된 보기는 다른 화면이 아니라 동일한 카드의 상세 상태이며, 명확하게 구분된 두 개의 섹션으로 구성됩니다.
+
+<Frame caption="확장된 에디터: 작업 섹션이 열려 있고 그 아래에 에이전트가 요약되어 있습니다.">
+  ![확장된 단계 에디터](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### 작업 — 무엇을 할지
+
+가장 자주 편집하는 항목이므로 기본적으로 열려 있습니다:
+
+- **이름**
+- **설명**
+- **예상 출력**
+- **응답 형식** — 다운스트림 단계(예: 라우팅)가 이 단계에서 무엇을 읽을지 정확히 제어하므로 여기에 표시됩니다.
+
+### 에이전트 — 누가 수행하는지
+
+할당된 에이전트는 요약으로 표시됩니다 — **이름, 모델, 도구가 인라인으로** 표시됩니다. 더 깊은 구성은 두 개의 접이식 섹션 뒤에 보존됩니다:
+
+- **역할, 목표 및 배경 스토리**
+- **에이전트 설정** — 추론, 최대 추론 시도 횟수, 위임 허용, 최대 반복 횟수, LLM 설정.
+
+<Tip>
+  에이전트의 전체 구성 — 역할, 목표, 배경 스토리, 모델, 도구, LLM 설정 및 전체 에이전트 설정 블록 — 은 **역할, 목표 및 배경 스토리**와 **에이전트 설정** 접이식 섹션 뒤에 편집 빈도에 따라 정리되어 있습니다.
+</Tip>
+
+## 에이전트 교체 vs. 편집
+
+카드에서 에이전트를 다루는 방식은 두 가지로 구분되며, 각각 다른 작업을 수행합니다:
+
+- **교체(Swap)** 는 *어떤* 에이전트가 이 작업을 수행할지 재할당합니다. **교체** 컨트롤을 사용하여 이 프로젝트의 다른 에이전트를 선택하거나, 에이전트 저장소에서 선택하거나, 새 에이전트를 만들 수 있습니다. 이는 작업 범위로 한정됩니다.
+- 에이전트 **편집** — **역할, 목표 및 배경 스토리** 또는 **에이전트 설정** 을 여는 것 — 은 에이전트 *자체*를 변경합니다.
+
+<Frame caption="교체는 작업을 수행할 에이전트를 변경합니다.">
+  ![에이전트 교체 패널](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **에이전트는 재사용 가능하며 공유됩니다.** 동일한 에이전트가 프로젝트 전반에서 둘 이상의 작업을 수행할 수 있습니다. 에이전트의 역할, 배경 스토리 또는 설정을 편집하면 열어 본 카드뿐만 아니라 **해당 에이전트가 사용되는 모든 곳**에서 업데이트됩니다. 변경 사항을 하나의 단계에만 적용하려면 공유 에이전트를 편집하지 말고 다른 에이전트로 **교체**하세요.
+</Warning>
+
+## 관련 항목
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/ko/enterprise/features/crew-studio" icon="pencil">
+    AI 지원과 비주얼 에디터로 자동화를 구축합니다.
+  </Card>
+  <Card title="에이전트 저장소" href="/ko/enterprise/features/agent-repositories" icon="users">
+    자동화 전반에서 에이전트를 관리하고 재사용합니다.
+  </Card>
+</CardGroup>

docs/v1.14.7/pt-BR/enterprise/features/merged-step-card.mdx

@@ -0,0 +1,82 @@
+---
+title: Um Card por Etapa
+description: "Cada etapa no canvas do Studio é um único card que combina a tarefa e o agente que a executa."
+icon: "layer-group"
+mode: "wide"
+---
+
+## Visão geral
+
+No canvas do Studio, cada etapa de trabalho é representada por um **único card**. O card combina dois elementos que antes ficavam em nós separados:
+
+- **A tarefa** — o que fazer (nome, descrição, saída esperada e formato da resposta).
+- **O agente** — quem faz (o agente atribuído, seu modelo e suas ferramentas).
+
+Um agente não é um participante independente do seu fluxo de trabalho — ele é um atributo da tarefa: *qual agente executa este trabalho.* Colocar a tarefa e seu agente em um único card torna essa relação explícita e transforma sua automação em uma única cadeia de unidades de trabalho, da esquerda para a direita, mais fácil de ler em uma olhada.
+
+<Frame caption="Um card por etapa: a tarefa com o agente atribuído resumido no rodapé.">
+  ![Cards de etapa unificados no canvas](/images/enterprise/merged-step-card-canvas.png)
+</Frame>
+
+## No canvas
+
+Cada card recolhido mostra:
+
+- O **nome e a descrição da tarefa** no topo.
+- Um **rodapé resumindo o agente atribuído** — avatar, nome, modelo e ferramentas.
+
+Não há nó de agente separado nem aresta vertical de agente → tarefa. Suas etapas se conectam diretamente umas às outras na ordem em que são executadas.
+
+## No editor
+
+Abra um card para editá-lo. A visão expandida é o mesmo card em um estado detalhado — não uma tela diferente — organizada em duas seções claramente identificadas.
+
+<Frame caption="O editor expandido: a seção da tarefa aberta, com o agente resumido abaixo.">
+  ![Editor de etapa expandido](/images/enterprise/merged-step-card-editor.png)
+</Frame>
+
+### A tarefa — o que fazer
+
+Aberta por padrão, já que é o que você costuma editar:
+
+- **Nome**
+- **Descrição**
+- **Saída Esperada**
+- **Formato da Resposta** — exibido aqui porque controla exatamente o que as etapas seguintes (como o roteamento) leem desta etapa.
+
+### O agente — quem faz
+
+O agente atribuído é mostrado como um resumo — **nome, modelo e ferramentas em linha**. Sua configuração mais detalhada é preservada por trás de duas seções recolhíveis:
+
+- **Papel, objetivo e história**
+- **Configurações do agente** — raciocínio, máximo de tentativas de raciocínio, permitir delegação, máximo de iterações e configurações de LLM.
+
+<Tip>
+  A configuração completa de um agente — Papel, Objetivo, História, Modelo, Ferramentas, Configurações de LLM e todo o bloco de Configurações do agente — fica por trás das seções recolhíveis **Papel, objetivo e história** e **Configurações do agente**, organizada pela frequência com que você a edita.
+</Tip>
+
+## Trocar vs. editar o agente
+
+Há duas maneiras distintas de trabalhar com o agente em um card, e elas fazem coisas diferentes:
+
+- **Trocar** reatribui *qual* agente executa esta tarefa. Use o controle **Trocar** para escolher um agente diferente deste projeto, selecionar um do seu Repositório de Agentes ou criar um novo agente. Isso tem escopo limitado à tarefa.
+- **Editar** o agente — abrindo **Papel, objetivo e história** ou **Configurações do agente** — altera o agente *em si*.
+
+<Frame caption="Trocar muda qual agente executa a tarefa.">
+  ![Painel de troca de agente](/images/enterprise/merged-step-card-swap-agent.png)
+</Frame>
+
+<Warning>
+  **Os agentes são reutilizáveis e compartilhados.** O mesmo agente pode executar mais de uma tarefa em todo o seu projeto. Editar o papel, a história ou as configurações de um agente atualiza esse agente **em todos os lugares onde ele é usado** — não apenas no card que você abriu. Se quiser que uma alteração se aplique a apenas uma etapa, **Troque** por um agente diferente em vez de editar o agente compartilhado.
+</Warning>
+
+## Relacionados
+
+<CardGroup cols={2}>
+  <Card title="Crew Studio" href="/pt-BR/enterprise/features/crew-studio" icon="pencil">
+    Crie automações com assistência de IA e um editor visual.
+  </Card>
+  <Card title="Repositórios de Agentes" href="/pt-BR/enterprise/features/agent-repositories" icon="users">
+    Gerencie e reutilize agentes em suas automações.
+  </Card>
+</CardGroup>

lib/cli/pyproject.toml

@@ -8,7 +8,7 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "crewai-core==1.14.8a2",
+    "crewai-core==1.14.8a5",
     "click>=8.1.7,<9",
     "pydantic>=2.11.9,<2.13",
     "pydantic-settings~=2.10.1",

lib/cli/src/crewai_cli/__init__.py

@@ -1 +1 @@
-__version__ = "1.14.8a2"
+__version__ = "1.14.8a5"

lib/cli/src/crewai_cli/cli.py

@@ -40,14 +40,6 @@ def replay_task_command(*args: Any, **kwargs: Any) -> Any:
     return _replay_task_command(*args, **kwargs)
 
 
-def run_flow_definition(*args: Any, **kwargs: Any) -> Any:
-    from crewai_cli.run_flow_definition import (
-        run_flow_definition as _run_flow_definition,
-    )
-
-    return _run_flow_definition(*args, **kwargs)
-
-
 def run_crew(*args: Any, **kwargs: Any) -> Any:
     from crewai_cli.run_crew import run_crew as _run_crew
 
@@ -155,12 +147,18 @@ def uv(uv_args: tuple[str, ...]) -> None:
     is_flag=True,
     help="Use classic Python/YAML project structure instead of JSON",
 )
+@click.option(
+    "--declarative",
+    is_flag=True,
+    help="Create a declarative Flow project instead of a Python Flow project",
+)
 def create(
     type: str | None,
     name: str | None,
     provider: str | None,
     skip_provider: bool = False,
     classic: bool = False,
+    declarative: bool = False,
 ) -> None:
     """Create a new crew, or flow."""
     dmn_mode = is_dmn_mode_enabled()
@@ -194,6 +192,8 @@ def create(
     if dmn_mode:
         skip_provider = True
     if type == "crew":
+        if declarative:
+            raise click.UsageError("--declarative can only be used with flow projects")
         if classic:
             from crewai_cli.create_crew import create_crew
 
@@ -205,7 +205,7 @@ def create(
     elif type == "flow":
         from crewai_cli.create_flow import create_flow
 
-        create_flow(name)
+        create_flow(name, declarative=declarative)
     else:
         click.secho("Error: Invalid type. Must be 'crew' or 'flow'.", fg="red")
 
@@ -468,7 +468,7 @@ def memory(
     type=str,
     default=None,
     help=(
-        "Path to a trained-agents pickle (produced by `crewai train -f`). "
+        "Crew-only: path to a trained-agents pickle (produced by `crewai train -f`). "
         "When set, agents load suggestions from this file instead of the "
         "default trained_agents_data.pkl. Equivalent to setting "
         "CREWAI_TRAINED_AGENTS_FILE."
@@ -512,16 +512,13 @@ def install(context: click.Context) -> None:
     "--definition",
     type=str,
     default=None,
-    help=(
-        "Experimental: path to a Flow Definition YAML/JSON file, "
-        "or an inline YAML/JSON string."
-    ),
+    help="Flow-only: path to a declarative flow definition.",
 )
 @click.option(
     "--inputs",
     type=str,
     default=None,
-    help='Experimental: JSON object passed to flow.kickoff(), e.g. \'{"topic":"AI"}\'.',
+    help='Flow-only: JSON object passed to the declarative flow, e.g. \'{"topic":"AI"}\'.',
 )
 def run(
     trained_agents_file: str | None,
@@ -531,16 +528,14 @@ def run(
     """Run the Crew or Flow."""
     if inputs is not None and definition is None:
         raise click.UsageError("--inputs requires --definition")
+    if trained_agents_file is not None and definition is not None:
+        raise click.UsageError("--filename can only be used when running crews")
 
-    if definition is not None:
-        click.secho(
-            "Warning: `crewai run --definition` is experimental and may change without notice.",
-            fg="yellow",
-        )
-        run_flow_definition(definition=definition, inputs=inputs)
-        return
-
-    run_crew(trained_agents_file=trained_agents_file)
+    run_crew(
+        trained_agents_file=trained_agents_file,
+        definition=definition,
+        inputs=inputs,
+    )
 
 
 @crewai.command()
@@ -795,10 +790,11 @@ def flow() -> None:
 @flow.command(name="kickoff")
 def flow_run() -> None:
     """Kickoff the Flow."""
-    from crewai_cli.kickoff_flow import kickoff_flow
-
-    click.echo("Running the Flow")
-    kickoff_flow()
+    click.secho(
+        "The command 'crewai flow kickoff' is deprecated. Use 'crewai run' instead.",
+        fg="yellow",
+    )
+    run_crew(trained_agents_file=None, definition=None, inputs=None)
 
 
 @flow.command(name="plot")

lib/cli/src/crewai_cli/create_flow.py

@@ -5,7 +5,10 @@ import click
 from crewai_core.telemetry import Telemetry
 
 
-def create_flow(name: str) -> None:
+DECLARATIVE_FLOW_FOLDERS = ("crews", "tools", "knowledge", "skills")
+
+
+def create_flow(name: str, *, declarative: bool = False) -> None:
     """Create a new flow."""
     folder_name = name.replace(" ", "_").replace("-", "_").lower()
     class_name = name.replace("_", " ").replace("-", " ").title().replace(" ", "")
@@ -20,6 +23,17 @@ def create_flow(name: str) -> None:
     telemetry = Telemetry()
     telemetry.flow_creation_span(class_name)
 
+    if declarative:
+        _create_declarative_flow(name, class_name, folder_name, project_root)
+    else:
+        _create_python_flow(name, class_name, folder_name, project_root)
+
+    click.secho(f"Flow {name} created successfully!", fg="green", bold=True)
+
+
+def _create_python_flow(
+    name: str, class_name: str, folder_name: str, project_root: Path
+) -> None:
     (project_root / "src" / folder_name).mkdir(parents=True)
     (project_root / "src" / folder_name / "crews").mkdir(parents=True)
     (project_root / "src" / folder_name / "tools").mkdir(parents=True)
@@ -92,4 +106,41 @@ def create_flow(name: str) -> None:
                 fg="yellow",
             )
 
-    click.secho(f"Flow {name} created successfully!", fg="green", bold=True)
+
+def _create_declarative_flow(
+    name: str, class_name: str, folder_name: str, project_root: Path
+) -> None:
+    project_root.mkdir(parents=True)
+    package_root = project_root / "src" / folder_name
+    package_root.mkdir(parents=True)
+    for folder in DECLARATIVE_FLOW_FOLDERS:
+        (package_root / folder).mkdir()
+
+    package_dir = Path(__file__).parent
+    templates_dir = package_dir / "templates" / "declarative_flow"
+
+    agents_md_src = package_dir / "templates" / "AGENTS.md"
+    if agents_md_src.exists():
+        shutil.copy2(agents_md_src, project_root / "AGENTS.md")
+
+    for src_file in templates_dir.rglob("*"):
+        if not src_file.is_file():
+            continue
+
+        relative_path = src_file.relative_to(templates_dir)
+        dst_file = (
+            project_root / relative_path
+            if relative_path.name in {".gitignore", "README.md", "pyproject.toml"}
+            else package_root / relative_path
+        )
+        dst_file.parent.mkdir(parents=True, exist_ok=True)
+        content = src_file.read_text(encoding="utf-8")
+        content = content.replace("{{name}}", name)
+        content = content.replace("{{flow_name}}", class_name)
+        content = content.replace("{{folder_name}}", folder_name)
+        dst_file.write_text(content, encoding="utf-8")
+
+    (project_root / ".env").write_text("OPENAI_API_KEY=YOUR_API_KEY", encoding="utf-8")
+    (package_root / "__init__.py").write_text("", encoding="utf-8")
+    for folder in DECLARATIVE_FLOW_FOLDERS:
+        (package_root / folder / ".gitkeep").write_text("", encoding="utf-8")

lib/cli/src/crewai_cli/create_json_crew.py

@@ -680,7 +680,7 @@ def _default_agents_and_tasks(
     ]
     crew_settings = {
         "process": "sequential",
-        "memory": False,
+        "memory": True,
         "inputs": {},
     }
     return agents, tasks, crew_settings

lib/cli/src/crewai_cli/crew_run_tui.py

@@ -17,7 +17,7 @@ from textual.binding import Binding, BindingType
 from textual.containers import Horizontal, Vertical, VerticalScroll
 from textual.css.query import NoMatches
 from textual.screen import ModalScreen
-from textual.widgets import Button, Footer, Header, Static
+from textual.widgets import Button, Footer, Header, Input, Static
 
 
 _SPINNER = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
@@ -382,6 +382,18 @@ Screen {
     height: auto;
 }
 
+#conversation-input {
+    display: none;
+    height: 3;
+    border-top: hkey #333333;
+    background: #1c1c1c;
+    color: #e0e0e0;
+}
+
+#conversation-input:focus {
+    border-top: hkey #1F7982;
+}
+
 Header {
     background: #1c1c1c;
     color: #FF5A50;
@@ -483,6 +495,7 @@ FooterKey .footer-key--key {
         total_tasks: int = 0,
         agent_names: list[str] | None = None,
         task_names: list[str] | None = None,
+        conversational: bool = False,
     ):
         super().__init__()
         self.title = f"CrewAI — {crew_name}"
@@ -544,6 +557,13 @@ FooterKey .footer-key--key {
         self._event_handlers: list[tuple[type, Any]] = []
 
         self._crew: Any = None
+        self._flow: Any = None
+        self._is_conversational = conversational
+        self._conversation_messages: list[tuple[str, str]] = []
+        self._conversation_turns = 0
+        self._conversation_turn_in_progress = False
+        self._conversation_previous_defer_trace_finalization: bool | None = None
+        self._conversation_exit_commands = {"exit", "quit"}
         self._default_inputs: dict[str, Any] | None = None
         self._crew_result: Any = None
         self._crew_json_path: Any = None
@@ -566,6 +586,10 @@ FooterKey .footer-key--key {
                 yield Static(id="task-header")
                 with VerticalScroll(id="scroll-area"):
                     yield Static(id="main-content")
+                yield Input(
+                    placeholder="Message the flow...",
+                    id="conversation-input",
+                )
                 with VerticalScroll(id="log-panel"):
                     yield Static(id="log-content")
         yield Footer()
@@ -574,7 +598,9 @@ FooterKey .footer-key--key {
         self._start_time = time.time()
         self._subscribe()
         self._tick_timer = self.set_interval(1 / 8, self._tick)
-        if self._crew:
+        if self._is_conversational and self._flow:
+            self._start_conversational_session()
+        elif self._crew:
             self._run_crew_worker()
         elif self._crew_json_path:
             self._load_and_run_worker()
@@ -725,6 +751,140 @@ FooterKey .footer-key--key {
         self._tick_timer = self.set_interval(1 / 2, self._tick)
         self._unsubscribe_if_no_running_memory_save(wait_for_queued=True)
 
+    # ── Conversational flow execution ───────────────────────
+
+    def _start_conversational_session(self) -> None:
+        from crewai.events.listeners.tracing.utils import (
+            set_suppress_tracing_messages,
+            set_tui_mode,
+        )
+
+        set_tui_mode(True)
+        set_suppress_tracing_messages(True)
+        with self._lock:
+            self._status = "chatting"
+            self._current_step = None
+            self._elapsed_frozen = None
+            self._conversation_previous_defer_trace_finalization = getattr(
+                self._flow, "defer_trace_finalization", False
+            )
+            self._flow.defer_trace_finalization = True
+
+        try:
+            input_widget = self.query_one("#conversation-input", Input)
+            input_widget.display = True
+            input_widget.focus()
+        except Exception:  # noqa: S110
+            pass
+
+    def _finalize_conversational_session(self) -> None:
+        if not (self._is_conversational and self._flow):
+            return
+        try:
+            self._flow.finalize_session_traces()
+        except Exception:  # noqa: S110
+            pass
+        previous = self._conversation_previous_defer_trace_finalization
+        if previous is not None:
+            try:
+                self._flow.defer_trace_finalization = previous
+            except Exception:  # noqa: S110
+                pass
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        if event.input.id != "conversation-input":
+            return
+        if not self._is_conversational:
+            return
+
+        message = event.value.strip()
+        event.input.value = ""
+        if not message:
+            return
+        if message.lower() in self._conversation_exit_commands:
+            self._finalize_conversational_session()
+            self._unsubscribe()
+            self.exit(self._crew_result)
+            return
+        if self._conversation_turn_in_progress:
+            return
+
+        with self._lock:
+            self._conversation_messages.append(("user", message))
+            self._conversation_turn_in_progress = True
+            self._conversation_turns += 1
+            self._status = "working"
+            self._current_step = ("yellow", "Thinking…", "")
+            self._is_streaming = False
+            self._streaming_text = ""
+            self._task_full_output = ""
+            self._current_llm_text = ""
+
+        event.input.disabled = True
+        self._run_conversation_turn_worker(message)
+
+    @work(thread=True, exclusive=True, group="conversation")
+    def _run_conversation_turn_worker(self, message: str) -> None:
+        from crewai.events.listeners.tracing.utils import (
+            set_suppress_tracing_messages,
+            set_tui_mode,
+        )
+
+        set_tui_mode(True)
+        set_suppress_tracing_messages(True)
+        try:
+            result = self._flow.handle_turn(message)
+            if hasattr(result, "get_full_text") and hasattr(result, "result"):
+                for _chunk in result:
+                    pass
+                result = result.result
+            self.call_from_thread(self._on_conversation_turn_done, result)
+        except Exception as e:
+            self.call_from_thread(self._on_conversation_turn_failed, str(e))
+
+    def _on_conversation_turn_done(self, result: Any) -> None:
+        with self._lock:
+            output = self._stringify_output(result)
+            self._conversation_messages.append(("assistant", output))
+            self._crew_result = result
+            self._conversation_turn_in_progress = False
+            self._status = "chatting"
+            self._is_streaming = False
+            self._streaming_text = ""
+            self._current_step = None
+        self._enable_conversation_input()
+        self._tick()
+        self._scroll_to_result()
+
+    def _on_conversation_turn_failed(self, error: str) -> None:
+        with self._lock:
+            self._status = "failed"
+            self._error = error
+            self._conversation_turn_in_progress = False
+            self._is_streaming = False
+            self._current_step = None
+        self._enable_conversation_input()
+        self._tick()
+
+    def _enable_conversation_input(self) -> None:
+        try:
+            input_widget = self.query_one("#conversation-input", Input)
+            input_widget.disabled = False
+            input_widget.focus()
+        except Exception:  # noqa: S110
+            pass
+
+    def _stringify_output(self, result: Any) -> str:
+        raw_result = getattr(result, "raw", result)
+        if raw_result is None:
+            return ""
+        if isinstance(raw_result, str):
+            return raw_result
+        try:
+            return _json.dumps(raw_result, default=str, ensure_ascii=False)
+        except TypeError:
+            return str(raw_result)
+
     # ── Actions ─────────────────────────────────────────────
 
     def action_toggle_sidebar(self) -> None:
@@ -783,6 +943,7 @@ FooterKey .footer-key--key {
             self._refresh_log_panel()
 
     async def action_quit(self) -> None:
+        self._finalize_conversational_session()
         self._unsubscribe()
         self.exit(self._crew_result)
 
@@ -958,6 +1119,30 @@ FooterKey .footer-key--key {
         t = Text()
         sidebar_width = 30
 
+        if self._is_conversational:
+            t.append("  CONVERSATION\n", style=f"bold {_C_PRIMARY}")
+            t.append("\n")
+            if self._conversation_turn_in_progress:
+                t.append(f"  {self._spinner()} ", style=_C_PRIMARY)
+                t.append("Working\n", style=f"bold {_C_TEXT}")
+            elif self._status == "failed":
+                t.append("  ✘ Failed\n", style=_C_RED)
+            else:
+                t.append("  ● Ready\n", style=_C_GREEN)
+            t.append(f"  Turns {self._conversation_turns}\n", style=_C_DIM)
+            t.append("\n")
+            t.append("  TOKENS\n", style=f"bold {_C_PRIMARY}")
+            t.append("\n")
+            out = self._output_tokens + self._live_out_tokens
+            t.append(f"  ↑ {self._input_tokens:,}\n", style=_C_DIM)
+            t.append(f"  ↓ {out:,}\n", style=_C_DIM)
+            t.append("\n")
+            t.append("  COMMANDS\n", style=f"bold {_C_PRIMARY}")
+            t.append("\n")
+            t.append("  quit / exit\n", style=_C_DIM)
+            widget.update(t)
+            return
+
         t.append("  TASKS\n", style=f"bold {_C_PRIMARY}")
         t.append("\n")
 
@@ -1011,6 +1196,22 @@ FooterKey .footer-key--key {
         widget = self.query_one("#task-header", Static)
         t = Text()
 
+        if self._is_conversational:
+            if self._status == "failed":
+                t.append("✘ ", style=f"bold {_C_RED}")
+                t.append("Failed", style=f"bold {_C_RED}")
+                if self._error:
+                    t.append(f"\n{self._error[:120]}", style=_C_RED)
+            elif self._conversation_turn_in_progress:
+                t.append(f"{self._spinner()} ", style=_C_PRIMARY)
+                t.append("Flow is responding", style=f"bold {_C_PRIMARY}")
+            else:
+                t.append("● ", style=f"bold {_C_GREEN}")
+                t.append("Conversational flow ready", style=f"bold {_C_GREEN}")
+                t.append("  Type a message below", style=_C_DIM)
+            widget.update(t)
+            return
+
         if self._status == "completed":
             elapsed = self._elapsed_frozen or (time.time() - self._start_time)
             t.append("✔ ", style=f"bold {_C_GREEN}")
@@ -1062,6 +1263,41 @@ FooterKey .footer-key--key {
         t = Text()
         should_scroll = False
 
+        if self._is_conversational:
+            if not self._conversation_messages and not self._is_streaming:
+                t.append("  Start the conversation below.\n", style=_C_MUTED)
+            for role, content in self._conversation_messages:
+                if role == "user":
+                    t.append("\n  You\n", style=f"bold {_C_TEAL}")
+                else:
+                    t.append("\n  Assistant\n", style=f"bold {_C_PRIMARY}")
+                rendered = _format_json_in_text(_unescape_text(content))
+                for line in rendered.split("\n"):
+                    style = _C_TEXT if role == "assistant" else _C_DIM
+                    t.append(f"  {line}\n", style=style)
+
+            if self._is_streaming and self._streaming_text:
+                text = _unescape_text(self._filtered_streaming_text())
+                if text.strip():
+                    t.append("\n  Assistant\n", style=f"bold {_C_PRIMARY}")
+                    for line in text.rstrip().split("\n")[-40:]:
+                        t.append(f"  {line}\n", style=_C_TEXT)
+                    should_scroll = True
+
+            if self._status == "failed" and self._error:
+                t.append("\n  Error\n", style=f"bold {_C_RED}")
+                t.append(f"  {self._error}\n", style=_C_RED)
+
+            widget.update(t)
+            if should_scroll:
+                try:
+                    self.query_one("#scroll-area", VerticalScroll).scroll_end(
+                        animate=False
+                    )
+                except Exception:  # noqa: S110
+                    pass
+            return
+
         # Plan section
         if self._plan and self._plan.get("steps"):
             plan_title = self._plan.get("plan", "Plan")

lib/cli/src/crewai_cli/deploy/archive.py

@@ -1,15 +1,11 @@
 from __future__ import annotations
 
 from pathlib import Path
-import re
 import shutil
 import tempfile
-from typing import Any
 import zipfile
 
 from crewai_cli import git
-from crewai_cli.deploy.validate import normalize_package_name
-from crewai_cli.utils import parse_toml
 
 
 _EXCLUDED_DIRS = {
@@ -38,8 +34,6 @@ _EXCLUDED_SUFFIXES = {
     ".pyc",
     ".pyo",
 }
-_SCRIPT_KEY_PATTERN = re.compile(r"^\s*(?P<key>[A-Za-z0-9_.-]+|\"[^\"]+\"|'[^']+')\s*=")
-_SECTION_PATTERN = re.compile(r"^\s*\[[^\]]+\]\s*(?:#.*)?$")
 
 
 def create_project_zip(
@@ -143,267 +137,7 @@ def _stage_project(root: Path, files: list[Path]) -> Path:
             destination = staging_root / relative_path
             destination.parent.mkdir(parents=True, exist_ok=True)
             shutil.copy2(source, destination)
-
-        if _is_json_crew_project(staging_root):
-            _add_json_crew_deploy_wrapper(staging_root)
     except Exception:
         shutil.rmtree(staging_root, ignore_errors=True)
         raise
     return staging_root
-
-
-def _is_json_crew_project(root: Path) -> bool:
-    """Return True for JSON crew projects that need a Python deploy wrapper."""
-    if not ((root / "crew.jsonc").is_file() or (root / "crew.json").is_file()):
-        return False
-
-    project = _read_pyproject(root)
-    tool_config = project.get("tool") or {}
-    crewai_config = tool_config.get("crewai") if isinstance(tool_config, dict) else None
-    declared_type = (
-        crewai_config.get("type") if isinstance(crewai_config, dict) else None
-    )
-    if declared_type == "flow":
-        return False
-
-    package_name = _package_name(root)
-    if package_name is None:
-        raise ValueError(
-            "Could not derive a valid Python package name from [project].name."
-        )
-
-    return not (root / "src" / package_name / "crew.py").is_file()
-
-
-def _read_pyproject(root: Path) -> dict[str, Any]:
-    """Read pyproject.toml, returning an empty mapping on missing or invalid data."""
-    pyproject_path = root / "pyproject.toml"
-    if not pyproject_path.is_file():
-        return {}
-    try:
-        pyproject = parse_toml(pyproject_path.read_text())
-    except Exception:
-        return {}
-    return pyproject if isinstance(pyproject, dict) else {}
-
-
-def _package_name(root: Path) -> str | None:
-    """Return the normalized Python package name for the project."""
-    project = _read_pyproject(root).get("project")
-    if not isinstance(project, dict):
-        return None
-
-    name = project.get("name")
-    if not isinstance(name, str) or not name.strip():
-        return None
-
-    package_name = normalize_package_name(name)
-    return package_name or None
-
-
-def _class_name(package_name: str) -> str:
-    """Return the generated wrapper class name for a package."""
-    parts = [part for part in re.split(r"[^a-zA-Z0-9]+", package_name) if part]
-    class_name = "".join(part[:1].upper() + part[1:] for part in parts)
-    if not class_name:
-        return "JsonCrew"
-    if class_name[0].isdigit():
-        return f"Crew{class_name}"
-    return class_name
-
-
-def _add_json_crew_deploy_wrapper(root: Path) -> None:
-    """Add Python wrapper files required to deploy a JSON crew project."""
-    package_name = _package_name(root)
-    if package_name is None:
-        raise ValueError(
-            "Could not derive a valid Python package name from [project].name."
-        )
-
-    package_dir = root / "src" / package_name
-    config_dir = package_dir / "config"
-    config_dir.mkdir(parents=True, exist_ok=True)
-
-    class_name = _class_name(package_name)
-    crew_filename = "crew.jsonc" if (root / "crew.jsonc").is_file() else "crew.json"
-
-    (package_dir / "__init__.py").write_text("", encoding="utf-8")
-    (config_dir / "agents.yaml").write_text("{}\n", encoding="utf-8")
-    (config_dir / "tasks.yaml").write_text("{}\n", encoding="utf-8")
-    (package_dir / "crew.py").write_text(
-        _json_crew_py(class_name, crew_filename),
-        encoding="utf-8",
-    )
-    (package_dir / "main.py").write_text(
-        _json_main_py(package_name, class_name),
-        encoding="utf-8",
-    )
-    _ensure_project_scripts(root, package_name)
-
-
-def _json_crew_py(class_name: str, crew_filename: str) -> str:
-    """Render the generated crew.py module for a JSON crew."""
-    return f'''from pathlib import Path
-
-from crewai import Crew
-from crewai.project import CrewBase, crew
-from crewai.project.crew_loader import load_crew
-
-
-def _crew_path() -> Path:
-    return Path(__file__).resolve().parents[2] / "{crew_filename}"
-
-
-@CrewBase
-class {class_name}:
-    """Compatibility wrapper for a JSON-defined CrewAI project."""
-
-    @crew
-    def crew(self) -> Crew:
-        crew_instance, default_inputs = load_crew(_crew_path())
-        self.default_inputs = default_inputs
-        return crew_instance
-'''
-
-
-def _json_main_py(package_name: str, class_name: str) -> str:
-    """Render the generated main.py entrypoints for a JSON crew."""
-    return f"""#!/usr/bin/env python
-import json
-import sys
-
-from {package_name}.crew import {class_name}
-
-
-def _load():
-    wrapper = {class_name}()
-    crew = wrapper.crew()
-    return crew, getattr(wrapper, "default_inputs", {{}})
-
-
-def run():
-    crew, inputs = _load()
-    return crew.kickoff(inputs=inputs)
-
-
-def train():
-    crew, inputs = _load()
-    return crew.train(
-        n_iterations=int(sys.argv[1]),
-        filename=sys.argv[2],
-        inputs=inputs,
-    )
-
-
-def replay():
-    crew, _ = _load()
-    return crew.replay(task_id=sys.argv[1])
-
-
-def test():
-    crew, inputs = _load()
-    return crew.test(
-        n_iterations=int(sys.argv[1]),
-        eval_llm=sys.argv[2],
-        inputs=inputs,
-    )
-
-
-def run_with_trigger():
-    if len(sys.argv) < 2:
-        raise ValueError("No trigger payload provided.")
-
-    crew, inputs = _load()
-    trigger_payload = json.loads(sys.argv[1])
-    return crew.kickoff(
-        inputs={{**inputs, "crewai_trigger_payload": trigger_payload}}
-    )
-"""
-
-
-def _ensure_project_scripts(root: Path, package_name: str) -> None:
-    """Ensure generated wrappers have project script entrypoints."""
-    pyproject_path = root / "pyproject.toml"
-    if not pyproject_path.is_file():
-        return
-
-    content = pyproject_path.read_text(encoding="utf-8")
-    entries = _project_script_entries(package_name)
-    pyproject_path.write_text(
-        _update_project_scripts(content, entries),
-        encoding="utf-8",
-    )
-
-
-def _project_script_entries(package_name: str) -> dict[str, str]:
-    """Return script entrypoints required by the generated JSON wrapper."""
-    return {
-        package_name: f"{package_name}.main:run",
-        "run_crew": f"{package_name}.main:run",
-        "train": f"{package_name}.main:train",
-        "replay": f"{package_name}.main:replay",
-        "test": f"{package_name}.main:test",
-        "run_with_trigger": f"{package_name}.main:run_with_trigger",
-    }
-
-
-def _update_project_scripts(content: str, entries: dict[str, str]) -> str:
-    """Add or replace generated script entries in pyproject.toml content."""
-    lines = content.rstrip().splitlines()
-    header_index = _project_scripts_header_index(lines)
-    if header_index is None:
-        return content.rstrip() + _project_scripts_block(entries)
-
-    end_index = _section_end_index(lines, header_index + 1)
-    seen: set[str] = set()
-    for index in range(header_index + 1, end_index):
-        key = _script_key(lines[index])
-        if key in entries:
-            lines[index] = _script_line(key, entries[key])
-            seen.add(key)
-
-    missing_lines = [
-        _script_line(key, value) for key, value in entries.items() if key not in seen
-    ]
-    lines[end_index:end_index] = missing_lines
-    return "\n".join(lines).rstrip() + "\n"
-
-
-def _project_scripts_header_index(lines: list[str]) -> int | None:
-    """Return the line index of the project scripts table, if present."""
-    for index, line in enumerate(lines):
-        if line.strip() == "[project.scripts]":
-            return index
-    return None
-
-
-def _section_end_index(lines: list[str], start_index: int) -> int:
-    """Return the exclusive end index for a TOML table section."""
-    for index in range(start_index, len(lines)):
-        if _SECTION_PATTERN.match(lines[index]):
-            return index
-    return len(lines)
-
-
-def _script_key(line: str) -> str | None:
-    """Return the script key for a pyproject script line."""
-    match = _SCRIPT_KEY_PATTERN.match(line)
-    if not match:
-        return None
-
-    key = match.group("key")
-    if key.startswith(("'", '"')) and key.endswith(("'", '"')):
-        return key[1:-1]
-    return key
-
-
-def _script_line(key: str, value: str) -> str:
-    """Render a project script TOML entry."""
-    return f'{key} = "{value}"'
-
-
-def _project_scripts_block(entries: dict[str, str]) -> str:
-    """Render a project scripts TOML table."""
-    lines = ["", "", "[project.scripts]"]
-    lines.extend(_script_line(key, value) for key, value in entries.items())
-    return "\n".join(lines) + "\n"

lib/cli/src/crewai_cli/deploy/validate.py

@@ -212,8 +212,16 @@ class DeployValidator:
         if crew_path is None:
             return self.results
 
+        agents_dir = self.project_root / "agents"
+
+        self._check_pyproject()
+        self._check_lockfile()
+        agents_dir_ok = self._check_json_agents_dir(agents_dir)
+
+        project = None
         try:
-            project = validate_crew_project(crew_path, self.project_root / "agents")
+            if agents_dir_ok:
+                project = validate_crew_project(crew_path, agents_dir)
         except JSONProjectValidationError as e:
             self._add(
                 Severity.ERROR,
@@ -232,15 +240,27 @@ class DeployValidator:
             )
             return self.results
 
-        agents_dir = self.project_root / "agents"
-
-        self._check_pyproject()
-        self._check_lockfile()
-        self._check_env_vars_json(crew_path, agents_dir, project.agent_names)
+        if project is not None:
+            self._check_env_vars_json(crew_path, agents_dir, project.agent_names)
         self._check_version_vs_lockfile()
 
         return self.results
 
+    def _check_json_agents_dir(self, agents_dir: Path) -> bool:
+        if agents_dir.is_dir():
+            return True
+        self._add(
+            Severity.ERROR,
+            "missing_agents_dir",
+            "Cannot find agents/ directory",
+            detail=(
+                "JSON crew projects load agent definitions from "
+                f"{agents_dir.relative_to(self.project_root)}/*.jsonc or *.json."
+            ),
+            hint="Create agents/ and add one JSON or JSONC file per agent.",
+        )
+        return False
+
     def _check_env_vars_json(
         self, crew_path: Path, agents_dir: Path, agent_names: list[str]
     ) -> None:

lib/cli/src/crewai_cli/experimental/skills/main.py

@@ -378,12 +378,40 @@ class SkillCommand(BaseCommand, PlusAPIMixin):
 
 
 def _safe_extractall(tf: tarfile.TarFile, dest: Path) -> None:
-    """Path-traversal-safe extraction for Python < 3.12."""
+    """Path-traversal-safe extraction for Python versions without tar filters.
+
+    Validates both the member's own path and, for symlink/hardlink members,
+    the link target. Without the link-target check a malicious archive can
+    plant a symlink that escapes ``dest`` (e.g. ``link -> /home/user/.ssh``)
+    followed by a regular member written *through* that link
+    (``link/authorized_keys``), escaping ``dest`` even though every member
+    name resolves inside it. This mirrors the protection that
+    ``tarfile.extractall(..., filter="data")`` provides when available.
+    """
     dest_resolved = dest.resolve()
     for member in tf.getmembers():
         member_path = (dest / member.name).resolve()
         if not member_path.is_relative_to(dest_resolved):
             raise ValueError(f"Blocked path traversal attempt: {member.name!r}")
+        if not (member.isfile() or member.isdir() or member.issym() or member.islnk()):
+            raise ValueError(f"Blocked unsupported tar member: {member.name!r}")
+        if member.issym() or member.islnk():
+            link_target = member.linkname
+            # Absolute link targets always escape the destination.
+            if os.path.isabs(link_target):
+                raise ValueError(
+                    f"Blocked link target escaping destination: "
+                    f"{member.name!r} -> {link_target!r}"
+                )
+            # Hardlink names are relative to the archive root; symlink
+            # targets are relative to the member's own directory.
+            anchor = dest if member.islnk() else (dest / member.name).parent
+            resolved_target = (anchor / link_target).resolve()
+            if not resolved_target.is_relative_to(dest_resolved):
+                raise ValueError(
+                    f"Blocked link target escaping destination: "
+                    f"{member.name!r} -> {link_target!r}"
+                )
     tf.extractall(dest)  # noqa: S202
 
 

lib/cli/src/crewai_cli/kickoff_flow.py

@@ -1,12 +1,94 @@
+from __future__ import annotations
+
+import importlib
+import inspect
+from pathlib import Path
 import subprocess
+import sys
+from typing import Any
 
 import click
 
 
+def _project_script_target(script_name: str) -> str | None:
+    try:
+        from crewai_cli.utils import read_toml
+
+        pyproject = read_toml()
+    except Exception:
+        return None
+
+    target = pyproject.get("project", {}).get("scripts", {}).get(script_name)
+    return target if isinstance(target, str) else None
+
+
+def _prepare_project_import_path() -> None:
+    cwd = Path.cwd()
+    for path in (cwd / "src", cwd):
+        path_str = str(path)
+        if path.exists() and path_str not in sys.path:
+            sys.path.insert(0, path_str)
+
+
+def _load_conversational_flow_from_kickoff_script() -> Any | None:
+    target = _project_script_target("kickoff")
+    if not target or ":" not in target:
+        return None
+
+    module_name, _callable_name = target.split(":", 1)
+    _prepare_project_import_path()
+
+    try:
+        module = importlib.import_module(module_name)
+        from crewai.flow.flow import Flow
+    except Exception:
+        return None
+
+    for value in vars(module).values():
+        if (
+            inspect.isclass(value)
+            and value is not Flow
+            and issubclass(value, Flow)
+            and getattr(value, "conversational", False)
+        ):
+            return value()
+
+    for value in vars(module).values():
+        if (
+            isinstance(value, Flow)
+            and getattr(value, "conversational", False)
+            and callable(getattr(value, "handle_turn", None))
+        ):
+            return value
+
+    return None
+
+
+def _run_conversational_flow_tui(flow: Any) -> Any:
+    from crewai_cli.crew_run_tui import CrewRunApp
+
+    app = CrewRunApp(
+        crew_name=getattr(flow, "name", None) or type(flow).__name__,
+        conversational=True,
+    )
+    app._flow = flow
+    app.run()
+
+    if app._status == "failed":
+        raise SystemExit(1)
+
+    return app._crew_result
+
+
 def kickoff_flow() -> None:
     """
     Kickoff the flow by running a command in the UV environment.
     """
+    flow = _load_conversational_flow_from_kickoff_script()
+    if flow is not None:
+        _run_conversational_flow_tui(flow)
+        return
+
     command = ["uv", "run", "kickoff"]
 
     try:

lib/cli/src/crewai_cli/plot_flow.py

@@ -5,19 +5,27 @@ import click
 
 def plot_flow() -> None:
     """
-    Plot the flow by running a command in the UV environment.
+    Plot the flow from declarative config or the Python UV entrypoint.
     """
-    command = ["uv", "run", "plot"]
+    from crewai_cli.run_declarative_flow import (
+        configured_project_declarative_flow,
+        plot_declarative_flow_in_project_env,
+    )
 
-    try:
-        result = subprocess.run(command, capture_output=False, text=True, check=True)  # noqa: S603
+    if definition := configured_project_declarative_flow():
+        plot_declarative_flow_in_project_env(definition)
+    else:
+        command = ["uv", "run", "plot"]
 
-        if result.stderr:
-            click.echo(result.stderr, err=True)
+        try:
+            subprocess.run(  # noqa: S603
+                command, capture_output=False, text=True, check=True
+            )
 
-    except subprocess.CalledProcessError as e:
-        click.echo(f"An error occurred while plotting the flow: {e}", err=True)
-        click.echo(e.output, err=True)
+        except subprocess.CalledProcessError as e:
+            click.echo(f"An error occurred while plotting the flow: {e}", err=True)
+            raise SystemExit(1) from e
 
-    except Exception as e:
-        click.echo(f"An unexpected error occurred: {e}", err=True)
+        except Exception as e:
+            click.echo(f"An unexpected error occurred: {e}", err=True)
+            raise SystemExit(1) from e

lib/cli/src/crewai_cli/run_crew.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from contextlib import AbstractContextManager, nullcontext
-from enum import Enum
 import os
 from pathlib import Path
 import re
@@ -27,11 +26,6 @@ if TYPE_CHECKING:
     from crewai_cli.crew_run_tui import CrewRunApp
 
 
-class CrewType(Enum):
-    STANDARD = "standard"
-    FLOW = "flow"
-
-
 # Must accept the same names as the kickoff interpolation pattern in
 # crewai.utilities.string_utils (_VARIABLE_PATTERN), including hyphens —
 # otherwise placeholders are interpolated at runtime but never prompted for.
@@ -537,7 +531,11 @@ def _print_post_tui_summary(app: CrewRunApp) -> None:
         )
 
 
-def run_crew(trained_agents_file: str | None = None) -> None:
+def run_crew(
+    trained_agents_file: str | None = None,
+    definition: str | None = None,
+    inputs: str | None = None,
+) -> None:
     """Run the crew or flow.
 
     Args:
@@ -545,15 +543,98 @@ def run_crew(trained_agents_file: str | None = None) -> None:
             by ``crewai train -f``. When set, exported as
             ``CREWAI_TRAINED_AGENTS_FILE`` so agents load suggestions from this
             file instead of the default ``trained_agents_data.pkl``.
+        definition: Optional path to a declarative Flow definition.
+        inputs: Optional JSON object passed to a declarative Flow.
     """
-    # JSON crew projects take precedence
+    if inputs is not None and definition is None:
+        raise click.UsageError("--inputs requires --definition")
+
+    if definition is not None:
+        _run_explicit_declarative_flow(
+            definition=definition,
+            inputs=inputs,
+            trained_agents_file=trained_agents_file,
+        )
+        return
+
     if _has_json_crew():
         _run_json_crew_in_project_env(trained_agents_file=trained_agents_file)
         return
 
+    pyproject_data = read_toml()
+    _warn_if_old_poetry_project(pyproject_data)
+    project_type = _get_project_type(pyproject_data)
+
+    if project_type == "flow":
+        _run_flow_project(
+            pyproject_data=pyproject_data,
+            trained_agents_file=trained_agents_file,
+        )
+        return
+
+    _run_classic_crew_project(
+        pyproject_data=pyproject_data,
+        trained_agents_file=trained_agents_file,
+    )
+
+
+def _run_explicit_declarative_flow(
+    definition: str, inputs: str | None, trained_agents_file: str | None
+) -> None:
+    if trained_agents_file is not None:
+        raise click.UsageError("--filename can only be used when running crews")
+
+    from crewai_cli.run_declarative_flow import run_declarative_flow
+
+    run_declarative_flow(definition=definition, inputs=inputs)
+
+
+def _run_flow_project(
+    pyproject_data: dict[str, Any], trained_agents_file: str | None
+) -> None:
+    if trained_agents_file is not None:
+        raise click.UsageError("--filename can only be used when running crews")
+
+    from crewai_cli.run_declarative_flow import (
+        configured_project_declarative_flow,
+        run_declarative_flow_in_project_env,
+    )
+
+    if definition := configured_project_declarative_flow(pyproject_data):
+        run_declarative_flow_in_project_env(definition=definition)
+        return
+
+    from crewai_cli.kickoff_flow import (
+        _load_conversational_flow_from_kickoff_script,
+        _run_conversational_flow_tui,
+    )
+
+    flow = _load_conversational_flow_from_kickoff_script()
+    if flow is not None:
+        _run_conversational_flow_tui(flow)
+        return
+
+    _execute_uv_script("kickoff", entity_type="flow")
+
+
+def _run_classic_crew_project(
+    pyproject_data: dict[str, Any], trained_agents_file: str | None
+) -> None:
+    _execute_uv_script(
+        "run_crew",
+        entity_type="crew",
+        trained_agents_file=trained_agents_file,
+    )
+
+
+def _get_project_type(pyproject_data: dict[str, Any]) -> str | None:
+    project_type = pyproject_data.get("tool", {}).get("crewai", {}).get("type")
+    return project_type if isinstance(project_type, str) else None
+
+
+def _warn_if_old_poetry_project(pyproject_data: dict[str, Any]) -> None:
     crewai_version = get_crewai_version()
     min_required_version = "0.71.0"
-    pyproject_data = read_toml()
 
     if pyproject_data.get("tool", {}).get("poetry") and (
         version.parse(crewai_version) < version.parse(min_required_version)
@@ -564,25 +645,22 @@ def run_crew(trained_agents_file: str | None = None) -> None:
             fg="red",
         )
 
-    is_flow = pyproject_data.get("tool", {}).get("crewai", {}).get("type") == "flow"
-    crew_type = CrewType.FLOW if is_flow else CrewType.STANDARD
 
-    click.echo(f"Running the {'Flow' if is_flow else 'Crew'}")
-
-    execute_command(crew_type, trained_agents_file=trained_agents_file)
-
-
-def execute_command(
-    crew_type: CrewType, trained_agents_file: str | None = None
+def _execute_uv_script(
+    script_name: str,
+    *,
+    entity_type: str,
+    trained_agents_file: str | None = None,
 ) -> None:
-    """Execute the appropriate command based on crew type.
+    """Execute a project script through uv.
 
     Args:
-        crew_type: The type of crew to run.
+        script_name: The project script to run.
+        entity_type: The user-facing entity being run.
         trained_agents_file: Optional trained-agents pickle path forwarded to
             the subprocess via the ``CREWAI_TRAINED_AGENTS_FILE`` env var.
     """
-    command = ["uv", "run", "kickoff" if crew_type == CrewType.FLOW else "run_crew"]
+    command = ["uv", "run", script_name]
 
     env = build_env_with_all_tool_credentials()
     if trained_agents_file:
@@ -592,21 +670,20 @@ def execute_command(
         subprocess.run(command, capture_output=False, text=True, check=True, env=env)  # noqa: S603
 
     except subprocess.CalledProcessError as e:
-        handle_error(e, crew_type)
+        _handle_run_error(e, entity_type)
 
     except Exception as e:
         click.echo(f"An unexpected error occurred: {e}", err=True)
 
 
-def handle_error(error: subprocess.CalledProcessError, crew_type: CrewType) -> None:
+def _handle_run_error(error: subprocess.CalledProcessError, entity_type: str) -> None:
     """
     Handle subprocess errors with appropriate messaging.
 
     Args:
         error: The subprocess error that occurred
-        crew_type: The type of crew that was being run
+        entity_type: The type of entity that was being run
     """
-    entity_type = "flow" if crew_type == CrewType.FLOW else "crew"
     click.echo(f"An error occurred while running the {entity_type}: {error}", err=True)
 
     if error.output:

lib/cli/src/crewai_cli/run_declarative_flow.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path, PureWindowsPath
+import subprocess
+from typing import Any
+
+import click
+from pydantic import ValidationError
+
+from crewai_cli.utils import build_env_with_all_tool_credentials
+
+
+def run_declarative_flow_in_project_env(
+    definition: str | Path, inputs: str | None = None
+) -> None:
+    """Run a declarative flow inside the project's Python environment."""
+    if is_declarative_flow_project_env() or not _has_project_file():
+        run_declarative_flow(definition=definition, inputs=inputs)
+        return
+
+    if inputs is not None:
+        raise click.UsageError("--inputs is only supported with --definition")
+
+    _execute_declarative_flow_command(["uv", "run", "crewai", "run"])
+
+
+def plot_declarative_flow_in_project_env(definition: str | Path) -> None:
+    """Plot a declarative flow inside the project's Python environment."""
+    if is_declarative_flow_project_env() or not _has_project_file():
+        plot_declarative_flow(definition=definition)
+        return
+
+    _execute_declarative_flow_command(["uv", "run", "crewai", "flow", "plot"])
+
+
+def run_declarative_flow(definition: str | Path, inputs: str | None = None) -> None:
+    """Run a declarative flow from a definition path."""
+    parsed_inputs = _parse_inputs(inputs)
+
+    try:
+        flow = load_declarative_flow(definition)
+        result = flow.kickoff(inputs=parsed_inputs)
+    except Exception as exc:
+        click.echo(
+            f"An error occurred while running the declarative flow: {exc}", err=True
+        )
+        raise SystemExit(1) from exc
+
+    click.echo(_format_result(result))
+
+
+def plot_declarative_flow(definition: str | Path) -> None:
+    """Plot a declarative flow from a definition path."""
+    try:
+        flow = load_declarative_flow(definition)
+        flow.plot()
+    except Exception as exc:
+        click.echo(
+            f"An error occurred while plotting the declarative flow: {exc}", err=True
+        )
+        raise SystemExit(1) from exc
+
+
+def load_declarative_flow(definition: str | Path) -> Any:
+    """Load a declarative Flow instance from a definition path."""
+    try:
+        from crewai.flow.flow import Flow
+    except ImportError as exc:
+        click.echo(
+            "Running declarative flows requires the full crewai package.",
+            err=True,
+        )
+        raise SystemExit(1) from exc
+
+    definition_path = Path(definition).expanduser()
+    try:
+        if not definition_path.is_file():
+            if definition_path.exists():
+                click.echo(
+                    f"Invalid --definition path: {definition} is not a file.",
+                    err=True,
+                )
+                raise SystemExit(1)
+            click.echo(
+                f"Invalid --definition path: {definition} does not exist.", err=True
+            )
+            raise SystemExit(1)
+    except OSError as exc:
+        click.echo(f"Invalid --definition path: {definition} ({exc})", err=True)
+        raise SystemExit(1) from exc
+
+    try:
+        return Flow.from_declaration(path=definition_path)
+    except (OSError, UnicodeError, ValueError, ValidationError) as exc:
+        click.echo(
+            f"Unable to read --definition path {definition_path}: {exc}",
+            err=True,
+        )
+        raise SystemExit(1) from exc
+
+
+def configured_project_declarative_flow(
+    pyproject_data: dict[str, Any] | None = None,
+    project_root: Path | None = None,
+) -> Path | None:
+    """Return the configured declarative flow source for flow projects."""
+    if pyproject_data is None:
+        try:
+            from crewai_cli.utils import read_toml
+
+            pyproject_data = read_toml()
+        except Exception:
+            return None
+
+    crewai_config = pyproject_data.get("tool", {}).get("crewai", {})
+    if crewai_config.get("type") != "flow":
+        return None
+    definition = crewai_config.get("definition")
+    if not isinstance(definition, str):
+        return None
+    definition = definition.strip()
+    if not definition:
+        return None
+
+    return _resolve_project_definition_path(
+        definition=definition,
+        project_root=project_root or Path.cwd(),
+    )
+
+
+def _resolve_project_definition_path(definition: str, project_root: Path) -> Path:
+    definition_path = Path(definition)
+    windows_definition_path = PureWindowsPath(definition)
+
+    if definition.startswith("~"):
+        raise click.UsageError(
+            "[tool.crewai] definition must be a project-local path; "
+            f"got {definition!r}."
+        )
+
+    if definition_path.is_absolute() or windows_definition_path.is_absolute():
+        raise click.UsageError(
+            "[tool.crewai] definition must be relative to the project root; "
+            f"got {definition!r}."
+        )
+
+    try:
+        root = project_root.resolve(strict=True)
+    except OSError as exc:
+        raise click.UsageError(
+            f"Invalid project root for [tool.crewai] definition: {exc}"
+        ) from exc
+
+    candidate = root / definition_path
+    try:
+        resolved_candidate = candidate.resolve(strict=False)
+    except OSError as exc:
+        raise click.UsageError(
+            f"Invalid [tool.crewai] definition path {definition!r}: {exc}"
+        ) from exc
+
+    if not resolved_candidate.is_relative_to(root):
+        raise click.UsageError(
+            "[tool.crewai] definition must resolve inside the project root; "
+            f"got {definition!r}."
+        )
+
+    if not resolved_candidate.exists():
+        raise click.UsageError(
+            "[tool.crewai] definition must point to an existing file; "
+            f"got {definition!r}."
+        )
+
+    if not resolved_candidate.is_file():
+        raise click.UsageError(
+            "[tool.crewai] definition must point to a regular file; "
+            f"got {definition!r}."
+        )
+
+    return resolved_candidate
+
+
+def _execute_declarative_flow_command(command: list[str]) -> None:
+    env = build_env_with_all_tool_credentials()
+
+    try:
+        subprocess.run(  # noqa: S603
+            command,
+            capture_output=False,
+            text=True,
+            check=True,
+            env=env,
+        )
+    except subprocess.CalledProcessError as e:
+        raise SystemExit(e.returncode) from e
+    except Exception as e:
+        click.echo(
+            f"An unexpected error occurred while running the declarative flow: {e}",
+            err=True,
+        )
+        raise SystemExit(1) from e
+
+
+def is_declarative_flow_project_env() -> bool:
+    import os
+
+    return os.environ.get("UV_RUN_RECURSION_DEPTH") is not None
+
+
+def _has_project_file(project_root: Path | None = None) -> bool:
+    root = project_root or Path.cwd()
+    return (root / "pyproject.toml").is_file()
+
+
+def _parse_inputs(inputs: str | None) -> dict[str, Any] | None:
+    if inputs is None:
+        return None
+
+    try:
+        parsed = json.loads(inputs)
+    except json.JSONDecodeError as exc:
+        click.echo(f"Invalid --inputs JSON: {exc}", err=True)
+        raise SystemExit(1) from exc
+
+    if not isinstance(parsed, dict):
+        click.echo("Invalid --inputs JSON: expected an object.", err=True)
+        raise SystemExit(1)
+
+    return parsed
+
+
+def _format_result(result: Any) -> str:
+    raw_result = getattr(result, "raw", result)
+    if isinstance(raw_result, str):
+        return raw_result
+
+    try:
+        return json.dumps(raw_result, default=str)
+    except TypeError:
+        return str(raw_result)

lib/cli/src/crewai_cli/run_flow_definition.py

@@ -1,113 +0,0 @@
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import Any
-
-import click
-
-
-def run_flow_definition(definition: str, inputs: str | None = None) -> None:
-    """Run a flow from a Flow Definition YAML/JSON string or file path."""
-    try:
-        from crewai.flow.flow import Flow
-        from crewai.flow.flow_definition import FlowDefinition
-    except ImportError as exc:
-        click.echo(
-            "Running flows from definitions requires the full crewai package.",
-            err=True,
-        )
-        raise SystemExit(1) from exc
-
-    parsed_inputs = _parse_inputs(inputs)
-    definition_source = _read_definition_source(definition)
-
-    try:
-        flow_definition = _parse_flow_definition(FlowDefinition, definition_source)
-        flow = Flow.from_definition(flow_definition)
-        result = flow.kickoff(inputs=parsed_inputs)
-    except Exception as exc:
-        click.echo(
-            f"An error occurred while running the flow definition: {exc}", err=True
-        )
-        raise SystemExit(1) from exc
-
-    click.echo(_format_result(result))
-
-
-def _parse_inputs(inputs: str | None) -> dict[str, Any] | None:
-    if inputs is None:
-        return None
-
-    try:
-        parsed = json.loads(inputs)
-    except json.JSONDecodeError as exc:
-        click.echo(f"Invalid --inputs JSON: {exc}", err=True)
-        raise SystemExit(1) from exc
-
-    if not isinstance(parsed, dict):
-        click.echo("Invalid --inputs JSON: expected an object.", err=True)
-        raise SystemExit(1)
-
-    return parsed
-
-
-def _read_definition_source(definition: str) -> str:
-    path = Path(definition).expanduser()
-    try:
-        is_file = path.is_file()
-    except OSError as exc:
-        if _looks_like_inline_definition(definition):
-            return definition
-        click.echo(f"Invalid --definition path: {definition} ({exc})", err=True)
-        raise SystemExit(1) from exc
-
-    if is_file:
-        try:
-            return path.read_text(encoding="utf-8")
-        except (OSError, UnicodeError) as exc:
-            click.echo(
-                f"Unable to read --definition path {path}: {exc}",
-                err=True,
-            )
-            raise SystemExit(1) from exc
-
-    try:
-        if path.exists():
-            click.echo(
-                f"Invalid --definition path: {definition} is not a file.", err=True
-            )
-            raise SystemExit(1)
-    except OSError as exc:
-        click.echo(f"Invalid --definition path: {definition} ({exc})", err=True)
-        raise SystemExit(1) from exc
-
-    return definition
-
-
-def _looks_like_inline_definition(definition: str) -> bool:
-    stripped = definition.lstrip()
-    return "\n" in definition or stripped.startswith(("{", "---")) or ":" in stripped
-
-
-def _parse_flow_definition(flow_definition_cls: type[Any], source: str) -> Any:
-    if _looks_like_json(source):
-        return flow_definition_cls.from_json(source)
-
-    return flow_definition_cls.from_yaml(source)
-
-
-def _looks_like_json(source: str) -> bool:
-    stripped = source.lstrip()
-    return stripped.startswith("{")
-
-
-def _format_result(result: Any) -> str:
-    raw_result = getattr(result, "raw", result)
-    if isinstance(raw_result, str):
-        return raw_result
-
-    try:
-        return json.dumps(raw_result, default=str)
-    except TypeError:
-        return str(raw_result)

lib/cli/src/crewai_cli/templates/AGENTS.md

@@ -62,7 +62,7 @@ crewai create flow <name> --skip_provider  # New flow project
 
 # Running
 crewai run                  # Run crew or flow (auto-detects from pyproject.toml)
-crewai flow kickoff         # Legacy flow execution
+crewai flow kickoff         # Deprecated compatibility alias for crewai run
 
 # Testing & training
 crewai test                           # Test crew (default: 2 iterations, gpt-4o-mini)

lib/cli/src/crewai_cli/templates/crew/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.14.8a2"
+    "crewai[tools]==1.14.8a5"
 ]
 
 [project.scripts]

lib/cli/src/crewai_cli/templates/declarative_flow/.gitignore

@@ -0,0 +1,5 @@
+.env
+.venv/
+__pycache__/
+.crewai/
+output/

lib/cli/src/crewai_cli/templates/declarative_flow/README.md

@@ -0,0 +1,17 @@
+# {{name}} Flow
+
+This project defines a declarative CrewAI Flow in `src/{{folder_name}}/flow.yaml`.
+
+## Install
+
+```bash
+crewai install
+```
+
+## Run
+
+```bash
+crewai run
+```
+
+Edit the declarative flow definition at `src/{{folder_name}}/flow.yaml` to change the flow. Add reusable crews under `src/{{folder_name}}/crews/`, custom Python tools under `src/{{folder_name}}/tools/`, and shared knowledge files under `src/{{folder_name}}/knowledge/`.

lib/cli/src/crewai_cli/templates/declarative_flow/flow.yaml

@@ -0,0 +1,15 @@
+schema: crewai.flow/v1
+name: {{flow_name}}
+description: A declarative CrewAI Flow.
+
+state:
+  type: dict
+  default:
+    topic: AI agents
+
+methods:
+  start:
+    start: true
+    do:
+      call: expression
+      expr: state.topic

lib/cli/src/crewai_cli/templates/declarative_flow/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "{{folder_name}}"
+version = "0.1.0"
+description = "{{name}} using crewAI"
+authors = [{ name = "Your Name", email = "you@example.com" }]
+requires-python = ">=3.10,<3.14"
+dependencies = [
+    "crewai[tools]==1.14.8a5"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{folder_name}}"]
+
+[tool.crewai]
+type = "flow"
+definition = "src/{{folder_name}}/flow.yaml"

lib/cli/src/crewai_cli/templates/flow/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.14.8a2"
+    "crewai[tools]==1.14.8a5"
 ]
 
 [project.scripts]

lib/cli/src/crewai_cli/templates/tool/pyproject.toml

@@ -5,7 +5,7 @@ description = "Power up your crews with {{folder_name}}"
 readme = "README.md"
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.14.8a2"
+    "crewai[tools]==1.14.8a5"
 ]
 
 [tool.crewai]

lib/cli/tests/deploy/test_archive.py

@@ -132,7 +132,7 @@ def test_create_project_zip_excludes_symlinked_files(tmp_path: Path):
     assert names == {"pyproject.toml"}
 
 
-def test_create_project_zip_adds_json_project_wrapper(tmp_path: Path):
+def test_create_project_zip_preserves_json_project_shape(tmp_path: Path):
     (tmp_path / "pyproject.toml").write_text(
         """
 [project]
@@ -157,8 +157,6 @@ type = "crew"
     try:
         with zipfile.ZipFile(archive_path) as archive:
             names = set(archive.namelist())
-            crew_py = archive.read("src/json_crew/crew.py").decode()
-            main_py = archive.read("src/json_crew/main.py").decode()
             pyproject = archive.read("pyproject.toml").decode()
     finally:
         archive_path.unlink(missing_ok=True)
@@ -166,18 +164,50 @@ type = "crew"
     assert "uv.lock" not in names
     assert "crew.jsonc" in names
     assert "agents/researcher.jsonc" in names
-    assert "src/json_crew/__init__.py" in names
-    assert "src/json_crew/crew.py" in names
-    assert "src/json_crew/main.py" in names
-    assert "src/json_crew/config/agents.yaml" in names
-    assert "src/json_crew/config/tasks.yaml" in names
-    assert "load_crew(_crew_path())" in crew_py
-    assert "JsonCrew" in crew_py
-    assert "from json_crew.crew import JsonCrew" in main_py
-    assert "run_crew = \"json_crew.main:run\"" in pyproject
+    assert all(not name.startswith("src/") for name in names)
+    assert "run_crew" not in pyproject
+    assert "json_crew =" not in pyproject
+    assert "[project.scripts]" not in pyproject
 
 
-def test_create_project_zip_updates_existing_json_project_scripts(tmp_path: Path):
+def test_create_project_zip_keeps_json_project_root_shape(tmp_path: Path):
+    (tmp_path / "pyproject.toml").write_text(
+        """
+[project]
+name = "json_crew"
+version = "0.1.0"
+dependencies = ["crewai[tools]==1.14.8a1"]
+
+[tool.crewai]
+type = "crew"
+""".strip()
+        + "\n"
+    )
+    (tmp_path / "uv.lock").write_text("# lock\n")
+    (tmp_path / "agents").mkdir()
+    (tmp_path / "agents" / "foo.jsonc").write_text("{}\n")
+    (tmp_path / "crew.jsonc").write_text("{}\n")
+
+    archive_path = create_project_zip("json_crew", project_dir=tmp_path)
+    try:
+        with zipfile.ZipFile(archive_path) as archive:
+            names = set(archive.namelist())
+            pyproject = archive.read("pyproject.toml").decode()
+    finally:
+        archive_path.unlink(missing_ok=True)
+
+    assert names == {
+        "agents/foo.jsonc",
+        "crew.jsonc",
+        "pyproject.toml",
+        "uv.lock",
+    }
+    assert "run_crew" not in pyproject
+    assert "json_crew =" not in pyproject
+    assert "[project.scripts]" not in pyproject
+
+
+def test_create_project_zip_does_not_rewrite_json_project_scripts(tmp_path: Path):
     (tmp_path / "pyproject.toml").write_text(
         """
 [project]
@@ -203,14 +233,10 @@ type = "crew"
     finally:
         archive_path.unlink(missing_ok=True)
 
-    assert 'json_crew = "json_crew.main:run"' in pyproject
-    assert 'run_crew = "json_crew.main:run"' in pyproject
-    assert 'train = "json_crew.main:train"' in pyproject
-    assert 'replay = "json_crew.main:replay"' in pyproject
-    assert 'test = "json_crew.main:test"' in pyproject
-    assert 'run_with_trigger = "json_crew.main:run_with_trigger"' in pyproject
+    assert 'json_crew = "old.module:run"' in pyproject
+    assert 'run_crew = "old.module:run"' in pyproject
     assert 'custom = "custom.module:main"' in pyproject
-    assert "old.module:run" not in pyproject
+    assert pyproject.count("[project.scripts]") == 1
     assert "[tool.crewai]" in pyproject
 
 
@@ -221,7 +247,7 @@ type = "crew"
         '[tool]\ncrewai = "invalid"\n',
     ],
 )
-def test_create_project_zip_adds_json_wrapper_for_malformed_tool_config(
+def test_create_project_zip_preserves_json_project_with_malformed_tool_config(
     tmp_path: Path, tool_config: str
 ):
     (tmp_path / "pyproject.toml").write_text(
@@ -244,12 +270,13 @@ version = "0.1.0"
     finally:
         archive_path.unlink(missing_ok=True)
 
-    assert "src/json_crew/crew.py" in names
-    assert "src/json_crew/main.py" in names
-    assert "run_crew = \"json_crew.main:run\"" in pyproject
+    assert names == {"crew.jsonc", "pyproject.toml"}
+    assert "run_crew" not in pyproject
+    assert "json_crew =" not in pyproject
+    assert "[project.scripts]" not in pyproject
 
 
-def test_create_project_zip_rejects_empty_normalized_package_name(tmp_path: Path):
+def test_create_project_zip_accepts_json_project_without_package_name(tmp_path: Path):
     (tmp_path / "pyproject.toml").write_text(
         """
 [project]
@@ -263,8 +290,15 @@ type = "crew"
     )
     (tmp_path / "crew.jsonc").write_text("{}\n")
 
-    with pytest.raises(
-        ValueError,
-        match=r"Could not derive a valid Python package name",
-    ):
-        create_project_zip("invalid", project_dir=tmp_path)
+    archive_path = create_project_zip("invalid", project_dir=tmp_path)
+    try:
+        with zipfile.ZipFile(archive_path) as archive:
+            names = set(archive.namelist())
+            pyproject = archive.read("pyproject.toml").decode()
+    finally:
+        archive_path.unlink(missing_ok=True)
+
+    assert names == {"crew.jsonc", "pyproject.toml"}
+    assert "run_crew" not in pyproject
+    assert "json_crew =" not in pyproject
+    assert "[project.scripts]" not in pyproject

lib/cli/tests/deploy/test_validate.py

@@ -200,6 +200,41 @@ def test_json_runtime_fields_are_deploy_errors(tmp_path: Path) -> None:
     assert "runtime-only" in finding.detail
 
 
+def test_json_crew_requires_agents_dir_without_classic_errors(tmp_path: Path) -> None:
+    _scaffold_json_crew(tmp_path)
+    for path in (tmp_path / "agents").iterdir():
+        path.unlink()
+    (tmp_path / "agents").rmdir()
+
+    v = DeployValidator(project_root=tmp_path)
+    v.run()
+
+    codes = _codes(v)
+    assert "missing_agents_dir" in codes
+    assert "missing_src_dir" not in codes
+    assert "missing_crew_py" not in codes
+    assert "missing_agents_yaml" not in codes
+    assert "missing_tasks_yaml" not in codes
+
+
+def test_json_crew_reports_project_metadata_before_invalid_json(
+    tmp_path: Path,
+) -> None:
+    _scaffold_json_crew(tmp_path)
+    (tmp_path / "pyproject.toml").unlink()
+    (tmp_path / "uv.lock").unlink()
+    (tmp_path / "crew.jsonc").write_text('{"agents": ["researcher"], "tasks": []}\n')
+
+    v = DeployValidator(project_root=tmp_path)
+    v.run()
+
+    codes = _codes(v)
+    assert "missing_pyproject" in codes
+    assert "missing_lockfile" in codes
+    assert "invalid_crew_json" in codes
+    assert "missing_src_dir" not in codes
+
+
 def test_missing_pyproject_errors(tmp_path: Path) -> None:
     v = _run_without_import_check(tmp_path)
     assert "missing_pyproject" in _codes(v)

lib/cli/tests/skills/test_safe_extract.py

@@ -0,0 +1,140 @@
+"""Regression tests for path-traversal-safe archive extraction.
+
+Guards against symlink/hardlink-based path traversal in the fallback used on
+Python versions without tarfile extraction filters. The filtered path relies on
+`tarfile.extractall(..., filter="data")`; the fallback must provide the same
+protection by validating link targets, not just member names.
+"""
+
+from __future__ import annotations
+
+import io
+import tarfile
+from pathlib import Path
+
+import pytest
+
+from crewai_cli.experimental.skills.main import _safe_extractall
+
+
+def _tar_from_members(build) -> tarfile.TarFile:
+    """Build an in-memory tar archive via `build(tf)` and return it for reading."""
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w") as tf:
+        build(tf)
+    buf.seek(0)
+    return tarfile.open(fileobj=buf, mode="r")
+
+
+def test_blocks_symlink_escaping_destination(tmp_path: Path) -> None:
+    """A symlink whose target escapes dest, plus a file written through it,
+    must be rejected before anything is extracted."""
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    dest = tmp_path / "dest"
+    dest.mkdir()
+
+    def build(tf: tarfile.TarFile) -> None:
+        link = tarfile.TarInfo("link")
+        link.type = tarfile.SYMTYPE
+        link.linkname = str(outside)  # absolute path outside dest
+        tf.addfile(link)
+        payload = b"pwned"
+        info = tarfile.TarInfo("link/evil.txt")
+        info.size = len(payload)
+        tf.addfile(info, io.BytesIO(payload))
+
+    with _tar_from_members(build) as tf:
+        with pytest.raises(ValueError, match="escaping destination"):
+            _safe_extractall(tf, dest)
+
+    assert not (outside / "evil.txt").exists()
+
+
+def test_blocks_relative_symlink_escaping_destination(tmp_path: Path) -> None:
+    """A relative symlink (../..) that escapes dest is also rejected."""
+    dest = tmp_path / "dest"
+    dest.mkdir()
+
+    def build(tf: tarfile.TarFile) -> None:
+        link = tarfile.TarInfo("sub/link")
+        link.type = tarfile.SYMTYPE
+        link.linkname = "../../outside"  # escapes dest from sub/
+        tf.addfile(link)
+
+    with _tar_from_members(build) as tf:
+        with pytest.raises(ValueError, match="escaping destination"):
+            _safe_extractall(tf, dest)
+
+
+def test_blocks_hardlink_escaping_destination(tmp_path: Path) -> None:
+    """A hardlink whose target escapes dest is rejected."""
+    dest = tmp_path / "dest"
+    dest.mkdir()
+
+    def build(tf: tarfile.TarFile) -> None:
+        link = tarfile.TarInfo("escape")
+        link.type = tarfile.LNKTYPE
+        link.linkname = "../outside.txt"  # escapes archive root
+        tf.addfile(link)
+
+    with _tar_from_members(build) as tf:
+        with pytest.raises(ValueError, match="escaping destination"):
+            _safe_extractall(tf, dest)
+
+
+def test_blocks_special_tar_member(tmp_path: Path) -> None:
+    """Special tar members such as FIFOs are rejected."""
+    dest = tmp_path / "dest"
+    dest.mkdir()
+
+    def build(tf: tarfile.TarFile) -> None:
+        fifo = tarfile.TarInfo("pipe")
+        fifo.type = tarfile.FIFOTYPE
+        tf.addfile(fifo)
+
+    with _tar_from_members(build) as tf:
+        with pytest.raises(ValueError, match="unsupported tar member"):
+            _safe_extractall(tf, dest)
+
+
+def test_allows_benign_relative_symlink(tmp_path: Path) -> None:
+    """A symlink that stays within dest is permitted."""
+    dest = tmp_path / "dest"
+    dest.mkdir()
+
+    def build(tf: tarfile.TarFile) -> None:
+        payload = b"hi"
+        info = tarfile.TarInfo("real.txt")
+        info.size = len(payload)
+        tf.addfile(info, io.BytesIO(payload))
+        link = tarfile.TarInfo("alias.txt")
+        link.type = tarfile.SYMTYPE
+        link.linkname = "real.txt"  # stays inside dest
+        tf.addfile(link)
+
+    with _tar_from_members(build) as tf:
+        _safe_extractall(tf, dest)
+
+    assert (dest / "real.txt").read_bytes() == b"hi"
+    assert (dest / "alias.txt").is_symlink()
+    assert (dest / "alias.txt").readlink() == Path("real.txt")
+
+
+def test_allows_benign_archive(tmp_path: Path) -> None:
+    """An ordinary archive of regular files extracts correctly."""
+    dest = tmp_path / "dest"
+    dest.mkdir()
+
+    def build(tf: tarfile.TarFile) -> None:
+        for name, body in (("SKILL.md", b"# skill"), ("scripts/run.py", b"print(1)")):
+            payload = body
+            info = tarfile.TarInfo(name)
+            info.size = len(payload)
+            tf.addfile(info, io.BytesIO(payload))
+
+    with _tar_from_members(build) as tf:
+        _safe_extractall(tf, dest)
+
+    assert (dest / "SKILL.md").read_bytes() == b"# skill"
+    assert (dest / "scripts" / "run.py").read_bytes() == b"print(1)"

lib/cli/tests/test_cli.py

@@ -12,6 +12,7 @@ from crewai_cli.cli import (
     deploy_remove,
     deply_status,
     flow_add_crew,
+    flow_run,
     login,
     reset_memories,
     run,
@@ -126,38 +127,75 @@ def test_run_uses_project_runner_by_default(run_crew, runner):
     result = runner.invoke(run)
 
     assert result.exit_code == 0
-    run_crew.assert_called_once_with(trained_agents_file=None)
+    run_crew.assert_called_once_with(
+        trained_agents_file=None,
+        definition=None,
+        inputs=None,
+    )
     assert "experimental" not in result.output.lower()
 
 
-@mock.patch("crewai_cli.cli.run_flow_definition")
-def test_run_with_definition_uses_definition_runner(run_flow_definition, runner):
+@mock.patch("crewai_cli.cli.run_crew")
+def test_run_with_definition_uses_project_runner(run_crew, runner):
     result = runner.invoke(
         run,
         ["--definition", "flow.yaml", "--inputs", '{"topic":"AI"}'],
     )
 
     assert result.exit_code == 0
-    assert (
-        "Warning: `crewai run --definition` is experimental and may change without notice."
-        in result.output
-    )
-    run_flow_definition.assert_called_once_with(
-        definition="flow.yaml", inputs='{"topic":"AI"}'
+    run_crew.assert_called_once_with(
+        trained_agents_file=None,
+        definition="flow.yaml",
+        inputs='{"topic":"AI"}',
     )
 
 
 @mock.patch("crewai_cli.cli.run_crew")
-@mock.patch("crewai_cli.cli.run_flow_definition")
-def test_run_rejects_inputs_without_definition(run_flow_definition, run_crew, runner):
+def test_run_rejects_inputs_without_definition(run_crew, runner):
     result = runner.invoke(run, ["--inputs", '{"topic":"AI"}'])
 
     assert result.exit_code == 2
     assert "Error: --inputs requires --definition" in result.output
-    run_flow_definition.assert_not_called()
     run_crew.assert_not_called()
 
 
+@mock.patch("crewai_cli.cli.run_crew")
+def test_run_rejects_filename_with_definition(run_crew, runner):
+    result = runner.invoke(run, ["--definition", "flow.yaml", "--filename", "x.pkl"])
+
+    assert result.exit_code == 2
+    assert "Error: --filename can only be used when running crews" in result.output
+    run_crew.assert_not_called()
+
+
+@mock.patch("crewai_cli.cli.run_crew")
+def test_run_passes_filename_to_project_runner(run_crew, runner):
+    result = runner.invoke(run, ["--filename", "trained.pkl"])
+
+    assert result.exit_code == 0
+    run_crew.assert_called_once_with(
+        trained_agents_file="trained.pkl",
+        definition=None,
+        inputs=None,
+    )
+
+
+@mock.patch("crewai_cli.cli.run_crew")
+def test_flow_kickoff_is_deprecated_and_uses_run_path(run_crew, runner):
+    result = runner.invoke(flow_run)
+
+    assert result.exit_code == 0
+    run_crew.assert_called_once_with(
+        trained_agents_file=None,
+        definition=None,
+        inputs=None,
+    )
+    assert (
+        "The command 'crewai flow kickoff' is deprecated. Use 'crewai run' instead."
+        in result.output
+    )
+
+
 @mock.patch("crewai_cli.create_json_crew.create_json_crew")
 def test_create_crew_in_dmn_mode_skips_provider_prompts(create_json_crew, runner):
     result = runner.invoke(create, ["crew", "DMN Crew"], env={"CREWAI_DMN": "True"})
@@ -166,6 +204,23 @@ def test_create_crew_in_dmn_mode_skips_provider_prompts(create_json_crew, runner
     create_json_crew.assert_called_once_with("DMN Crew", None, True)
 
 
+@mock.patch("crewai_cli.create_flow.create_flow")
+def test_create_flow_declarative_uses_declarative_scaffold(create_flow, runner):
+    result = runner.invoke(create, ["flow", "My Flow", "--declarative"])
+
+    assert result.exit_code == 0
+    create_flow.assert_called_once_with("My Flow", declarative=True)
+
+
+@mock.patch("crewai_cli.create_json_crew.create_json_crew")
+def test_create_crew_rejects_declarative_flag(create_json_crew, runner):
+    result = runner.invoke(create, ["crew", "My Crew", "--declarative"])
+
+    assert result.exit_code == 2
+    assert "--declarative can only be used with flow projects" in result.output
+    create_json_crew.assert_not_called()
+
+
 def test_create_requires_type_in_dmn_mode(runner):
     result = runner.invoke(create, env={"CREWAI_DMN": "True"})
 

lib/cli/tests/test_create_crew.py

@@ -712,8 +712,26 @@ def test_json_create_provider_preselects_default_model(tmp_path, monkeypatch):
         default_llm="openai/gpt-5.5",
     )
     assert (tmp_path / "json_crew" / "crew.jsonc").exists()
+    assert not (tmp_path / "json_crew" / "src").exists()
     assert not (tmp_path / "json_crew" / "tests").exists()
     assert not (tmp_path / "json_crew" / "config.jsonc").exists()
+    generated_paths = {
+        path.relative_to(tmp_path / "json_crew").as_posix()
+        for path in (tmp_path / "json_crew").rglob("*")
+        if path.is_file()
+    }
+    assert not any(
+        path.endswith("/crew.py") or path == "crew.py" for path in generated_paths
+    )
+    assert not any(
+        path.endswith("/agents.yaml") or path == "agents.yaml"
+        for path in generated_paths
+    )
+    assert not any(
+        path.endswith("/tasks.yaml") or path == "tasks.yaml"
+        for path in generated_paths
+    )
+    assert not any(path.startswith("src/") for path in generated_paths)
 
     pyproject = tomli.loads((tmp_path / "json_crew" / "pyproject.toml").read_text())
     dependency = pyproject["project"]["dependencies"][0]
@@ -849,7 +867,7 @@ def test_json_create_dmn_mode_uses_non_interactive_defaults(tmp_path, monkeypatc
     crew_template = (project_root / "crew.jsonc").read_text()
     agent_template = (project_root / "agents" / "researcher.jsonc").read_text()
 
-    assert '"memory": false' in crew_template
+    assert '"memory": true' in crew_template
     assert '"description": "Research current AI trends and write a concise summary."' in (
         crew_template
     )

lib/cli/tests/test_create_flow.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from click.testing import CliRunner
+from pytest import MonkeyPatch
+import tomli
+
+from crewai_cli.cli import crewai
+from crewai_cli.create_flow import create_flow
+
+
+def test_create_flow_declarative_project_can_run(
+    tmp_path: Path, monkeypatch: MonkeyPatch
+):
+    monkeypatch.chdir(tmp_path)
+    create_flow("Research Flow", declarative=True)
+
+    project_root = tmp_path / "research_flow"
+    assert project_root.is_dir()
+
+    pyproject = tomli.loads(
+        (project_root / "pyproject.toml").read_text(encoding="utf-8")
+    )
+    assert pyproject["project"]["name"] == "research_flow"
+    assert pyproject["project"]["requires-python"]
+    assert pyproject["project"]["dependencies"]
+    assert (project_root / pyproject["tool"]["crewai"]["definition"]).is_file()
+
+    monkeypatch.chdir(project_root)
+    result = CliRunner().invoke(crewai, ["run"], env={"UV_RUN_RECURSION_DEPTH": "1"})
+
+    assert result.exit_code == 0
+    assert "Running the Flow" not in result.output
+    assert "AI agents" in result.output

lib/cli/tests/test_crew_run_tui.py

@@ -126,6 +126,52 @@ def test_chain_deploy_does_not_login_for_deploy_exit(monkeypatch, capsys) -> Non
     assert "Deploy failed with exit code 42" in capsys.readouterr().out
 
 
+def test_conversation_turn_done_records_assistant_message() -> None:
+    class RawResult:
+        raw = "hello from the flow"
+
+    app = CrewRunApp(conversational=True)
+    app._conversation_turn_in_progress = True
+    app._enable_conversation_input = lambda: None  # type: ignore[method-assign]
+    app._tick = lambda: None  # type: ignore[method-assign]
+    app._scroll_to_result = lambda: None  # type: ignore[method-assign]
+
+    app._on_conversation_turn_done(RawResult())
+
+    assert app._conversation_messages == [("assistant", "hello from the flow")]
+    assert app._conversation_turn_in_progress is False
+    assert app._status == "chatting"
+    assert isinstance(app._crew_result, RawResult)
+
+
+@pytest.mark.asyncio
+async def test_conversation_input_submits_turn() -> None:
+    class FakeFlow:
+        defer_trace_finalization = False
+
+        def handle_turn(self, message: str) -> str:
+            return f"reply: {message}"
+
+        def finalize_session_traces(self) -> None:
+            pass
+
+    app = CrewRunApp(crew_name="Demo", conversational=True)
+    app._flow = FakeFlow()
+
+    async with app.run_test() as pilot:
+        await pilot.click("#conversation-input")
+        await pilot.press("h", "i", "enter")
+        for _ in range(50):
+            await pilot.pause(0.05)
+            if app._conversation_messages[-1:] == [("assistant", "reply: hi")]:
+                break
+
+    assert app._conversation_messages == [
+        ("user", "hi"),
+        ("assistant", "reply: hi"),
+    ]
+
+
 def test_plan_step_status_updates_only_the_explicit_step() -> None:
     app = _app_with_plan()
 

lib/cli/tests/test_flow_commands.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from pathlib import Path
+import subprocess
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from crewai_cli.cli import flow_run
+import crewai_cli.plot_flow as plot_flow_module
+
+
+FLOW_YAML = """\
+schema: crewai.flow/v1
+name: TestFlow
+config:
+  suppress_flow_events: true
+methods:
+  begin:
+    start: true
+    do:
+      call: expression
+      expr: "'AI'"
+"""
+
+
+def _write_flow_project(project_root: Path) -> None:
+    (project_root / "flow.yaml").write_text(FLOW_YAML, encoding="utf-8")
+    (project_root / "pyproject.toml").write_text(
+        '[project]\nname = "demo"\n\n'
+        '[tool.crewai]\ntype = "flow"\ndefinition = "flow.yaml"\n',
+        encoding="utf-8",
+    )
+
+
+def test_flow_kickoff_runs_configured_declarative_definition(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    _write_flow_project(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("UV_RUN_RECURSION_DEPTH", "1")
+
+    result = CliRunner().invoke(flow_run)
+
+    assert result.exit_code == 0
+    assert (
+        "The command 'crewai flow kickoff' is deprecated. Use 'crewai run' instead."
+        in result.output
+    )
+    assert "AI\n" in result.output
+    assert "Running the Flow" not in result.output
+
+
+def test_plot_flow_runs_configured_declarative_definition(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    _write_flow_project(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("UV_RUN_RECURSION_DEPTH", "1")
+
+    plot_flow_module.plot_flow()
+
+
+def test_flow_kickoff_delegates_to_run_crew(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    calls = []
+
+    monkeypatch.setattr(
+        "crewai_cli.cli.run_crew",
+        lambda **kwargs: calls.append(kwargs),
+    )
+
+    result = CliRunner().invoke(flow_run)
+
+    assert result.exit_code == 0
+    assert calls == [
+        {"trained_agents_file": None, "definition": None, "inputs": None},
+    ]
+
+
+def test_plot_flow_keeps_python_entrypoint_without_definition(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    subprocess_calls = []
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(
+        subprocess,
+        "run",
+        lambda command, **kwargs: subprocess_calls.append((command, kwargs)),
+    )
+
+    plot_flow_module.plot_flow()
+
+    assert subprocess_calls == [
+        (
+            ["uv", "run", "plot"],
+            {"capture_output": False, "text": True, "check": True},
+        )
+    ]
+
+
+def test_configured_project_declarative_flow(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(FLOW_YAML, encoding="utf-8")
+    (tmp_path / "pyproject.toml").write_text(
+        '[tool.crewai]\ntype = "flow"\ndefinition = " flow.yaml "\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    assert configured_project_declarative_flow() == definition_path.resolve()
+
+
+@pytest.mark.parametrize(
+    ("definition", "expected_error"),
+    [
+        ("C:/tmp/flow.yaml", "must be relative to the project root"),
+        ("~/flow.yaml", "must be a project-local path"),
+        ("../flow.yaml", "must resolve inside the project root"),
+    ],
+)
+def test_configured_project_declarative_flow_rejects_unsafe_paths(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    definition: str,
+    expected_error: str,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "pyproject.toml").write_text(
+        f'[tool.crewai]\ntype = "flow"\ndefinition = "{definition}"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    with pytest.raises(click.UsageError) as exc_info:
+        configured_project_declarative_flow()
+
+    assert expected_error in exc_info.value.message
+
+
+def test_configured_project_declarative_flow_allows_normalized_project_path(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(FLOW_YAML, encoding="utf-8")
+    (tmp_path / "src").mkdir()
+    (tmp_path / "pyproject.toml").write_text(
+        '[tool.crewai]\ntype = "flow"\ndefinition = "src/../flow.yaml"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    assert configured_project_declarative_flow() == definition_path.resolve()
+
+
+def test_configured_project_declarative_flow_rejects_absolute_path(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    definition = tmp_path / "flow.yaml"
+    (tmp_path / "pyproject.toml").write_text(
+        f'[tool.crewai]\ntype = "flow"\ndefinition = "{definition.as_posix()}"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    with pytest.raises(click.UsageError) as exc_info:
+        configured_project_declarative_flow()
+
+    assert "must be relative to the project root" in exc_info.value.message
+
+
+def test_configured_project_declarative_flow_rejects_symlink_escape(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    outside_definition = tmp_path.parent / "outside-flow.yaml"
+    outside_definition.write_text(FLOW_YAML, encoding="utf-8")
+    link = tmp_path / "flow.yaml"
+    try:
+        link.symlink_to(outside_definition)
+    except (NotImplementedError, OSError) as exc:
+        pytest.skip(f"symlinks unavailable: {exc}")
+
+    (tmp_path / "pyproject.toml").write_text(
+        '[tool.crewai]\ntype = "flow"\ndefinition = "flow.yaml"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    with pytest.raises(click.UsageError) as exc_info:
+        configured_project_declarative_flow()
+
+    assert "must resolve inside the project root" in exc_info.value.message
+
+
+def test_configured_project_declarative_flow_rejects_missing_file(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "pyproject.toml").write_text(
+        '[tool.crewai]\ntype = "flow"\ndefinition = "missing-flow.yaml"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    with pytest.raises(click.UsageError) as exc_info:
+        configured_project_declarative_flow()
+
+    assert "must point to an existing file" in exc_info.value.message
+
+
+def test_configured_project_declarative_flow_rejects_directory(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "flow.yaml").mkdir()
+    (tmp_path / "pyproject.toml").write_text(
+        '[tool.crewai]\ntype = "flow"\ndefinition = "flow.yaml"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    with pytest.raises(click.UsageError) as exc_info:
+        configured_project_declarative_flow()
+
+    assert "must point to a regular file" in exc_info.value.message

lib/cli/tests/test_kickoff_flow.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import sys
+
+from crewai_cli import kickoff_flow
+
+
+def test_loads_conversational_flow_from_kickoff_script(tmp_path, monkeypatch) -> None:
+    package_dir = tmp_path / "src" / "demo_chat"
+    package_dir.mkdir(parents=True)
+    (package_dir / "__init__.py").write_text("")
+    (package_dir / "main.py").write_text(
+        "\n".join(
+            [
+                "from crewai.flow import Flow",
+                "",
+                "class DemoChatFlow(Flow):",
+                "    conversational = True",
+            ]
+        )
+    )
+    (tmp_path / "pyproject.toml").write_text(
+        "\n".join(
+            [
+                "[project]",
+                'name = "demo-chat"',
+                "[project.scripts]",
+                'kickoff = "demo_chat.main:kickoff"',
+            ]
+        )
+    )
+    monkeypatch.chdir(tmp_path)
+    sys.modules.pop("demo_chat.main", None)
+    sys.modules.pop("demo_chat", None)
+
+    flow = kickoff_flow._load_conversational_flow_from_kickoff_script()
+
+    assert flow is not None
+    assert type(flow).__name__ == "DemoChatFlow"
+    assert flow.conversational is True
+
+
+def test_kickoff_flow_falls_back_to_uv_when_no_conversational_flow(
+    monkeypatch,
+) -> None:
+    calls: list[list[str]] = []
+
+    def fake_run(command, capture_output, text, check):
+        calls.append(command)
+
+        class Result:
+            stderr = ""
+
+        return Result()
+
+    monkeypatch.setattr(
+        kickoff_flow, "_load_conversational_flow_from_kickoff_script", lambda: None
+    )
+    monkeypatch.setattr(kickoff_flow.subprocess, "run", fake_run)
+
+    kickoff_flow.kickoff_flow()
+
+    assert calls == [["uv", "run", "kickoff"]]

lib/cli/tests/test_run_crew.py

@@ -568,3 +568,175 @@ def test_has_json_crew_true_without_pyproject(monkeypatch, tmp_path: Path):
     (tmp_path / "crew.jsonc").write_text("{}")
 
     assert run_crew_module._has_json_crew() is True
+
+
+def test_run_crew_rejects_inputs_without_definition():
+    with pytest.raises(click.UsageError) as exc_info:
+        run_crew_module.run_crew(inputs='{"topic":"AI"}')
+
+    assert "--inputs requires --definition" in exc_info.value.message
+
+
+def test_run_crew_rejects_filename_with_explicit_definition():
+    with pytest.raises(click.UsageError) as exc_info:
+        run_crew_module.run_crew(
+            trained_agents_file="trained.pkl",
+            definition="flow.yaml",
+        )
+
+    assert "--filename can only be used when running crews" in exc_info.value.message
+
+
+def test_run_crew_runs_explicit_declarative_definition(monkeypatch, capsys):
+    calls = []
+
+    def fake_run_declarative_flow(definition: str, inputs: str | None = None):
+        calls.append((definition, inputs))
+
+    monkeypatch.setattr(
+        "crewai_cli.run_declarative_flow.run_declarative_flow",
+        fake_run_declarative_flow,
+    )
+
+    run_crew_module.run_crew(definition="flow.yaml", inputs='{"topic":"AI"}')
+
+    captured = capsys.readouterr()
+    assert "experimental" not in captured.out.lower()
+    assert calls == [("flow.yaml", '{"topic":"AI"}')]
+
+
+def test_run_crew_runs_classic_crew_project(monkeypatch, capsys):
+    calls = []
+
+    monkeypatch.setattr(run_crew_module, "_has_json_crew", lambda: False)
+    monkeypatch.setattr(
+        run_crew_module,
+        "read_toml",
+        lambda: {"tool": {"crewai": {"type": "crew"}}},
+    )
+    monkeypatch.setattr(
+        run_crew_module,
+        "_execute_uv_script",
+        lambda script_name, **kwargs: calls.append((script_name, kwargs)),
+    )
+
+    run_crew_module.run_crew(trained_agents_file="trained.pkl")
+
+    assert capsys.readouterr().out == ""
+    assert calls == [
+        (
+            "run_crew",
+            {"entity_type": "crew", "trained_agents_file": "trained.pkl"},
+        )
+    ]
+
+
+def test_run_crew_runs_python_flow_project(monkeypatch, capsys):
+    calls = []
+
+    monkeypatch.setattr(run_crew_module, "_has_json_crew", lambda: False)
+    monkeypatch.setattr(
+        run_crew_module,
+        "read_toml",
+        lambda: {"tool": {"crewai": {"type": "flow"}}},
+    )
+    monkeypatch.setattr(
+        run_crew_module,
+        "_execute_uv_script",
+        lambda script_name, **kwargs: calls.append((script_name, kwargs)),
+    )
+    monkeypatch.setattr(
+        "crewai_cli.kickoff_flow._load_conversational_flow_from_kickoff_script",
+        lambda: None,
+    )
+
+    run_crew_module.run_crew()
+
+    assert capsys.readouterr().out == ""
+    assert calls == [("kickoff", {"entity_type": "flow"})]
+
+
+def test_run_crew_runs_conversational_flow_tui(monkeypatch, capsys):
+    class Flow:
+        pass
+
+    flow = Flow()
+    calls = []
+
+    monkeypatch.setattr(run_crew_module, "_has_json_crew", lambda: False)
+    monkeypatch.setattr(
+        run_crew_module,
+        "read_toml",
+        lambda: {"tool": {"crewai": {"type": "flow"}}},
+    )
+    monkeypatch.setattr(
+        "crewai_cli.kickoff_flow._load_conversational_flow_from_kickoff_script",
+        lambda: flow,
+    )
+    monkeypatch.setattr(
+        "crewai_cli.kickoff_flow._run_conversational_flow_tui",
+        lambda loaded_flow: calls.append(loaded_flow),
+    )
+    monkeypatch.setattr(
+        run_crew_module,
+        "_execute_uv_script",
+        lambda *_args, **_kwargs: pytest.fail(
+            "conversational flows must use the TUI"
+        ),
+    )
+
+    run_crew_module.run_crew()
+
+    assert capsys.readouterr().out == ""
+    assert calls == [flow]
+
+
+def test_run_crew_rejects_filename_for_flow_project(monkeypatch):
+    monkeypatch.setattr(run_crew_module, "_has_json_crew", lambda: False)
+    monkeypatch.setattr(
+        run_crew_module,
+        "read_toml",
+        lambda: {"tool": {"crewai": {"type": "flow"}}},
+    )
+
+    with pytest.raises(click.UsageError) as exc_info:
+        run_crew_module.run_crew(trained_agents_file="trained.pkl")
+
+    assert "--filename can only be used when running crews" in exc_info.value.message
+
+
+def test_run_crew_runs_configured_declarative_flow_project(
+    monkeypatch, tmp_path: Path, capsys
+):
+    calls = []
+
+    monkeypatch.chdir(tmp_path)
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text("schema: crewai.flow/v1\n", encoding="utf-8")
+    monkeypatch.setattr(run_crew_module, "_has_json_crew", lambda: False)
+    monkeypatch.setattr(
+        run_crew_module,
+        "read_toml",
+        lambda: {
+            "tool": {
+                "crewai": {
+                    "type": "flow",
+                    "definition": "flow.yaml",
+                }
+            }
+        },
+    )
+    monkeypatch.setattr(
+        "crewai_cli.run_declarative_flow.run_declarative_flow_in_project_env",
+        lambda definition, inputs=None: calls.append((definition, inputs)),
+    )
+    monkeypatch.setattr(
+        run_crew_module,
+        "_execute_uv_script",
+        lambda *_args, **_kwargs: pytest.fail("declarative flows must not run kickoff"),
+    )
+
+    run_crew_module.run_crew()
+
+    assert capsys.readouterr().out == ""
+    assert calls == [(definition_path.resolve(), None)]

lib/cli/tests/test_run_declarative_flow.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+import crewai_cli.run_declarative_flow as run_declarative_flow_module
+
+
+FLOW_YAML = """\
+schema: crewai.flow/v1
+name: TestFlow
+config:
+  suppress_flow_events: true
+methods:
+  begin:
+    start: true
+    do:
+      call: expression
+      expr: state.topic
+"""
+
+
+def test_run_declarative_flow_reads_definition_file(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(FLOW_YAML, encoding="utf-8")
+
+    run_declarative_flow_module.run_declarative_flow(
+        str(definition_path), '{"topic":"AI"}'
+    )
+
+    assert capsys.readouterr().out == "AI\n"
+
+
+def test_run_declarative_flow_rejects_non_object_inputs(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(FLOW_YAML, encoding="utf-8")
+
+    with pytest.raises(SystemExit):
+        run_declarative_flow_module.run_declarative_flow(
+            str(definition_path), '["not", "an", "object"]'
+        )
+
+    assert "Invalid --inputs JSON: expected an object." in capsys.readouterr().err
+
+
+def test_run_declarative_flow_reports_missing_file(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    with pytest.raises(SystemExit):
+        run_declarative_flow_module.run_declarative_flow("missing-flow.yaml")
+
+    assert (
+        "Invalid --definition path: missing-flow.yaml does not exist."
+        in capsys.readouterr().err
+    )
+
+
+def test_run_declarative_flow_reports_empty_file(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(" \n", encoding="utf-8")
+
+    with pytest.raises(SystemExit):
+        run_declarative_flow_module.run_declarative_flow(str(definition_path))
+
+    assert "Flow declaration file is empty" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize(
+    "contents, expected_error",
+    [
+        ("[]\n", "Flow declaration must contain a mapping"),
+        ("schema: crewai.flow/v1\nmethods: {}\n", "Field required"),
+    ],
+)
+def test_load_declarative_flow_reports_invalid_declarations(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+    contents: str,
+    expected_error: str,
+) -> None:
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(contents, encoding="utf-8")
+
+    with pytest.raises(SystemExit) as exc_info:
+        run_declarative_flow_module.load_declarative_flow(str(definition_path))
+
+    assert exc_info.value.code == 1
+    stderr = capsys.readouterr().err
+    assert f"Unable to read --definition path {definition_path}:" in stderr
+    assert expected_error in stderr
+
+
+def test_run_declarative_flow_in_project_env_uses_uv(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    subprocess_calls = []
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("UV_RUN_RECURSION_DEPTH", raising=False)
+    (tmp_path / "pyproject.toml").write_text("[project]\nname = 'demo'\n")
+    monkeypatch.setattr(
+        run_declarative_flow_module,
+        "build_env_with_all_tool_credentials",
+        lambda: {"EXISTING": "value"},
+    )
+    monkeypatch.setattr(
+        run_declarative_flow_module.subprocess,
+        "run",
+        lambda command, **kwargs: subprocess_calls.append((command, kwargs)),
+    )
+
+    run_declarative_flow_module.run_declarative_flow_in_project_env("flow.yaml")
+
+    assert subprocess_calls == [
+        (
+            ["uv", "run", "crewai", "run"],
+            {
+                "capture_output": False,
+                "text": True,
+                "check": True,
+                "env": {"EXISTING": "value"},
+            },
+        )
+    ]
+
+
+def test_run_declarative_flow_in_process_inside_uv(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("UV_RUN_RECURSION_DEPTH", "1")
+    (tmp_path / "pyproject.toml").write_text("[project]\nname = 'demo'\n")
+    (tmp_path / "flow.yaml").write_text(FLOW_YAML, encoding="utf-8")
+
+    run_declarative_flow_module.run_declarative_flow_in_project_env(
+        "flow.yaml", '{"topic":"AI"}'
+    )
+
+    assert capsys.readouterr().out == "AI\n"

lib/cli/tests/test_run_flow_definition.py

@@ -1,156 +0,0 @@
-from __future__ import annotations
-
-import json
-import sys
-import types
-
-import pytest
-import yaml
-
-from crewai_cli.run_flow_definition import run_flow_definition
-
-
-class _FakeFlow:
-    def __init__(self, definition):
-        self.definition = definition
-
-    def kickoff(self, inputs=None):
-        return {
-            "flow": self.definition["name"],
-            "inputs": inputs or {},
-        }
-
-
-class _FakeFlowFactory:
-    @classmethod
-    def from_definition(cls, definition):
-        return _FakeFlow(definition)
-
-
-class _FakeFlowDefinition:
-    @classmethod
-    def from_yaml(cls, source):
-        return yaml.safe_load(source)
-
-    @classmethod
-    def from_json(cls, source):
-        return json.loads(source)
-
-
-@pytest.fixture
-def fake_flow_runtime(monkeypatch):
-    crewai_module = types.ModuleType("crewai")
-    flow_package = types.ModuleType("crewai.flow")
-    flow_module = types.ModuleType("crewai.flow.flow")
-    flow_definition_module = types.ModuleType("crewai.flow.flow_definition")
-
-    flow_module.Flow = _FakeFlowFactory
-    flow_definition_module.FlowDefinition = _FakeFlowDefinition
-
-    monkeypatch.setitem(sys.modules, "crewai", crewai_module)
-    monkeypatch.setitem(sys.modules, "crewai.flow", flow_package)
-    monkeypatch.setitem(sys.modules, "crewai.flow.flow", flow_module)
-    monkeypatch.setitem(
-        sys.modules, "crewai.flow.flow_definition", flow_definition_module
-    )
-
-
-def _captured_json(capsys):
-    return json.loads(capsys.readouterr().out)
-
-
-def test_run_flow_definition_reads_definition_file(
-    tmp_path, capsys, fake_flow_runtime
-):
-    definition_path = tmp_path / "flow.yaml"
-    definition_path.write_text("schema: crewai.flow/v1\nname: TestFlow\n")
-
-    run_flow_definition(str(definition_path), '{"topic":"AI"}')
-
-    assert _captured_json(capsys) == {
-        "flow": "TestFlow",
-        "inputs": {"topic": "AI"},
-    }
-
-
-@pytest.mark.parametrize(
-    ("definition_source", "expected_flow_name"),
-    [
-        pytest.param(
-            "schema: crewai.flow/v1\nname: InlineFlow\n",
-            "InlineFlow",
-            id="inline-yaml",
-        ),
-        pytest.param(
-            '{"schema":"crewai.flow/v1","name":"InlineJsonFlow"}',
-            "InlineJsonFlow",
-            id="inline-json",
-        ),
-        pytest.param(
-            '{"schema":"crewai.flow/v1","name":"' + ("JsonFlow" * 500) + '"}',
-            "JsonFlow" * 500,
-            id="large-inline-json",
-        ),
-    ],
-)
-def test_run_flow_definition_accepts_inline_definitions(
-    definition_source, expected_flow_name, capsys, fake_flow_runtime
-):
-    run_flow_definition(definition_source)
-
-    assert _captured_json(capsys) == {"flow": expected_flow_name, "inputs": {}}
-
-
-@pytest.mark.parametrize(
-    ("filename", "definition_source", "expected_flow_name"),
-    [
-        pytest.param(
-            "flow.yaml",
-            "schema: crewai.flow/v1\nname: YamlFileFlow\n",
-            "YamlFileFlow",
-            id="yaml-file",
-        ),
-        pytest.param(
-            "flow.json",
-            '{"schema":"crewai.flow/v1","name":"JsonFlow"}',
-            "JsonFlow",
-            id="json-file",
-        ),
-    ],
-)
-def test_run_flow_definition_accepts_definition_files(
-    filename, definition_source, expected_flow_name, tmp_path, capsys, fake_flow_runtime
-):
-    definition_path = tmp_path / filename
-    definition_path.write_text(definition_source)
-
-    run_flow_definition(str(definition_path))
-
-    assert _captured_json(capsys) == {"flow": expected_flow_name, "inputs": {}}
-
-
-def test_run_flow_definition_rejects_non_object_inputs(fake_flow_runtime, capsys):
-    with pytest.raises(SystemExit):
-        run_flow_definition("name: TestFlow", '["not", "an", "object"]')
-
-    assert "Invalid --inputs JSON: expected an object." in capsys.readouterr().err
-
-
-def test_run_flow_definition_reports_unreadable_file(
-    monkeypatch, tmp_path, capsys, fake_flow_runtime
-):
-    definition_path = tmp_path / "flow.yaml"
-    definition_path.write_text("schema: crewai.flow/v1\nname: TestFlow\n")
-
-    def raise_permission_error(self, *args, **kwargs):
-        raise PermissionError("no access")
-
-    monkeypatch.setattr("pathlib.Path.read_text", raise_permission_error)
-
-    with pytest.raises(SystemExit):
-        run_flow_definition(str(definition_path))
-
-    err = capsys.readouterr().err
-    assert "Unable to read --definition path" in err
-    assert str(definition_path) in err
-    assert "no access" in err

lib/crewai-core/pyproject.toml

@@ -16,9 +16,9 @@ dependencies = [
     "pyjwt>=2.13.0,<3",
     "pydantic>=2.11.9,<2.13",
     "rich>=13.7.1",
-    "opentelemetry-api~=1.34.0",
-    "opentelemetry-sdk~=1.34.0",
-    "opentelemetry-exporter-otlp-proto-http~=1.34.0",
+    "opentelemetry-api~=1.42.0",
+    "opentelemetry-sdk~=1.42.0",
+    "opentelemetry-exporter-otlp-proto-http~=1.42.0",
     "tomli~=2.0.2",
 ]
 

lib/crewai-core/src/crewai_core/__init__.py

@@ -1 +1 @@
-__version__ = "1.14.8a2"
+__version__ = "1.14.8a5"

lib/crewai-files/src/crewai_files/__init__.py

@@ -152,4 +152,4 @@ __all__ = [
     "wrap_file_source",
 ]
 
-__version__ = "1.14.8a2"
+__version__ = "1.14.8a5"

lib/crewai-tools/pyproject.toml

@@ -10,7 +10,7 @@ requires-python = ">=3.10, <3.14"
 dependencies = [
     "pytube~=15.0.0",
     "requests>=2.33.0,<3",
-    "crewai==1.14.8a2",
+    "crewai==1.14.8a5",
     "tiktoken>=0.8.0,<0.13",
     "beautifulsoup4~=4.13.4",
     "python-docx~=1.2.0",
@@ -131,7 +131,7 @@ postgresql = [
 ]
 bedrock = [
     "beautifulsoup4>=4.13.4",
-    "bedrock-agentcore>=0.1.0",
+    "bedrock-agentcore>=1.7.0,<1.8.0",
     "playwright>=1.52.0",
     "nest-asyncio>=1.6.0",
 ]

lib/crewai-tools/src/crewai_tools/__init__.py

@@ -330,4 +330,4 @@ __all__ = [
     "ZapierActionTools",
 ]
 
-__version__ = "1.14.8a2"
+__version__ = "1.14.8a5"

lib/crewai/pyproject.toml

@@ -8,8 +8,8 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "crewai-core==1.14.8a2",
-    "crewai-cli==1.14.8a2",
+    "crewai-core==1.14.8a5",
+    "crewai-cli==1.14.8a5",
     # Core Dependencies
     "pydantic>=2.11.9,<2.13",
     "openai>=2.30.0,<3",
@@ -18,9 +18,9 @@ dependencies = [
     "pdfplumber~=0.11.4",
     "regex~=2026.1.15",
     # Telemetry and Monitoring
-    "opentelemetry-api~=1.34.0",
-    "opentelemetry-sdk~=1.34.0",
-    "opentelemetry-exporter-otlp-proto-http~=1.34.0",
+    "opentelemetry-api~=1.42.0",
+    "opentelemetry-sdk~=1.42.0",
+    "opentelemetry-exporter-otlp-proto-http~=1.42.0",
     # Data Handling
     "chromadb~=1.1.0",
     "tokenizers>=0.21,<1",
@@ -55,7 +55,7 @@ Repository = "https://github.com/crewAIInc/crewAI"
 
 [project.optional-dependencies]
 tools = [
-    "crewai-tools==1.14.8a2",
+    "crewai-tools==1.14.8a5",
 ]
 embeddings = [
     "tiktoken>=0.8.0,<0.13"
@@ -78,8 +78,8 @@ qdrant = [
     "qdrant-client[fastembed]~=1.14.3",
 ]
 aws = [
-    "boto3~=1.42.79",
-    "aiobotocore~=3.4.0",
+    "boto3~=1.42.90",
+    "aiobotocore~=3.5.0",
 ]
 watson = [
     "ibm-watsonx-ai~=1.3.39",
@@ -91,7 +91,7 @@ litellm = [
     "litellm>=1.84.0,<2",
 ]
 bedrock = [
-    "boto3~=1.42.79",
+    "boto3~=1.42.90",
 ]
 google-genai = [
     "google-genai~=1.65.0",

lib/crewai/src/crewai/__init__.py

@@ -48,7 +48,7 @@ def _suppress_pydantic_deprecation_warnings() -> None:
 
 _suppress_pydantic_deprecation_warnings()
 
-__version__ = "1.14.8a2"
+__version__ = "1.14.8a5"
 
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "Memory": ("crewai.memory.unified_memory", "Memory"),

lib/crewai/src/crewai/agents/crew_agent_executor.py

@@ -57,6 +57,7 @@ from crewai.utilities.agent_utils import (
     convert_tools_to_openai_schema,
     enforce_rpm_limit,
     format_message_for_llm,
+    format_native_tool_output_for_agent,
     get_llm_response,
     handle_agent_action_core,
     handle_context_length,
@@ -907,19 +908,31 @@ class CrewAgentExecutor(BaseAgentExecutor):
         ):
             max_usage_reached = True
 
+        structured_tool: CrewStructuredTool | None = None
+        if original_tool is not None:
+            for structured in self.tools or []:
+                if getattr(structured, "_original_tool", None) is original_tool:
+                    structured_tool = structured
+                    break
+        if structured_tool is None:
+            for structured in self.tools or []:
+                if sanitize_tool_name(structured.name) == func_name:
+                    structured_tool = structured
+                    break
+
+        output_tool = original_tool or structured_tool
+
         from_cache = False
         result: str = "Tool not found"
+        raw_tool_result: Any = result
         input_str = json.dumps(args_dict) if args_dict else ""
-        if self.tools_handler and self.tools_handler.cache:
+        if self.tools_handler and self.tools_handler.cache and output_tool is not None:
             cached_result = self.tools_handler.cache.read(
                 tool=func_name, input=input_str
             )
             if cached_result is not None:
-                result = (
-                    str(cached_result)
-                    if not isinstance(cached_result, str)
-                    else cached_result
-                )
+                raw_tool_result = cached_result
+                result = format_native_tool_output_for_agent(output_tool, cached_result)
                 from_cache = True
 
         agent_key = getattr(self.agent, "key", "unknown") if self.agent else "unknown"
@@ -938,18 +951,6 @@ class CrewAgentExecutor(BaseAgentExecutor):
 
         track_delegation_if_needed(func_name, args_dict or {}, self.task)
 
-        structured_tool: CrewStructuredTool | None = None
-        if original_tool is not None:
-            for structured in self.tools or []:
-                if getattr(structured, "_original_tool", None) is original_tool:
-                    structured_tool = structured
-                    break
-        if structured_tool is None:
-            for structured in self.tools or []:
-                if sanitize_tool_name(structured.name) == func_name:
-                    structured_tool = structured
-                    break
-
         hook_blocked = False
         before_hook_context = ToolCallHookContext(
             tool_name=func_name,
@@ -975,11 +976,18 @@ class CrewAgentExecutor(BaseAgentExecutor):
 
         if hook_blocked:
             result = f"Tool execution blocked by hook. Tool: {func_name}"
+            raw_tool_result = result
         elif max_usage_reached and original_tool:
             result = f"Tool '{func_name}' has reached its usage limit of {original_tool.max_usage_count} times and cannot be used anymore."
-        elif not from_cache and func_name in available_functions:
+            raw_tool_result = result
+        elif (
+            not from_cache
+            and func_name in available_functions
+            and output_tool is not None
+        ):
             try:
                 raw_result = available_functions[func_name](**(args_dict or {}))
+                raw_tool_result = raw_result
 
                 if self.tools_handler and self.tools_handler.cache:
                     should_cache = True
@@ -996,11 +1004,10 @@ class CrewAgentExecutor(BaseAgentExecutor):
                             tool=func_name, input=input_str, output=raw_result
                         )
 
-                result = (
-                    str(raw_result) if not isinstance(raw_result, str) else raw_result
-                )
+                result = format_native_tool_output_for_agent(output_tool, raw_result)
             except Exception as e:
                 result = f"Error executing tool: {e}"
+                raw_tool_result = result
                 if self.task:
                     self.task.increment_tools_errors()
                 crewai_event_bus.emit(
@@ -1024,6 +1031,7 @@ class CrewAgentExecutor(BaseAgentExecutor):
             task=self.task,
             crew=self.crew,
             tool_result=result,
+            raw_tool_result=raw_tool_result,
         )
         after_hooks = get_after_tool_call_hooks()
         try:

lib/crewai/src/crewai/agents/tools_handler.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+from typing import Any
 
 from pydantic import BaseModel, Field
 
@@ -25,14 +26,14 @@ class ToolsHandler(BaseModel):
     def on_tool_use(
         self,
         calling: ToolCalling | InstructorToolCalling,
-        output: str,
+        output: Any,
         should_cache: bool = True,
     ) -> None:
         """Run when tool ends running.
 
         Args:
             calling: The tool calling instance.
-            output: The output from the tool execution.
+            output: The raw output from the tool execution.
             should_cache: Whether to cache the tool output.
         """
         self.last_used_tool = calling

lib/crewai/src/crewai/events/utils/console_formatter.py

@@ -373,9 +373,6 @@ To enable tracing, do any one of these:
         status: str = "running",
     ) -> None:
         """Show method status panel."""
-        if not self.verbose:
-            return
-
         if status == "running":
             style = "yellow"
             panel_title = "🔄 Flow Method Running"

lib/crewai/src/crewai/experimental/agent_executor.py

@@ -54,7 +54,7 @@ from crewai.events.types.tool_usage_events import (
     ToolUsageFinishedEvent,
     ToolUsageStartedEvent,
 )
-from crewai.flow.flow import Flow, StateProxy, listen, or_, router, start
+from crewai.flow.flow import Flow, listen, or_, router, start
 from crewai.flow.types import FlowMethodName
 from crewai.hooks.llm_hooks import (
     get_after_llm_call_hooks,
@@ -80,6 +80,7 @@ from crewai.utilities.agent_utils import (
     enforce_rpm_limit,
     extract_tool_call_info,
     format_message_for_llm,
+    format_native_tool_output_for_agent,
     get_llm_response,
     handle_agent_action_core,
     handle_context_length,
@@ -275,11 +276,6 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
         """
         return self.llm.supports_stop_words() if self.llm else False
 
-    @property
-    def state(self) -> AgentExecutorState:
-        """Get thread-safe state proxy."""
-        return StateProxy(self._state, self._state_lock)  # type: ignore[return-value]
-
     @property  # type: ignore[misc]
     def iterations(self) -> int:
         """Compatibility property for mixin - returns state iterations."""
@@ -1905,19 +1901,32 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
         ):
             max_usage_reached = True
 
+        structured_tool: CrewStructuredTool | None = None
+        if original_tool is not None:
+            for structured in self.tools or []:
+                if getattr(structured, "_original_tool", None) is original_tool:
+                    structured_tool = structured
+                    break
+        if structured_tool is None:
+            for structured in self.tools or []:
+                if sanitize_tool_name(structured.name) == func_name:
+                    structured_tool = structured
+                    break
+
+        output_tool = original_tool or structured_tool
+
         # Check cache before executing
         from_cache = False
+        result = "Tool not found"
+        raw_tool_result: Any = result
         input_str = json.dumps(args_dict) if args_dict else ""
-        if self.tools_handler and self.tools_handler.cache:
+        if self.tools_handler and self.tools_handler.cache and output_tool is not None:
             cached_result = self.tools_handler.cache.read(
                 tool=func_name, input=input_str
             )
             if cached_result is not None:
-                result = (
-                    str(cached_result)
-                    if not isinstance(cached_result, str)
-                    else cached_result
-                )
+                raw_tool_result = cached_result
+                result = format_native_tool_output_for_agent(output_tool, cached_result)
                 from_cache = True
 
         # Emit tool usage started event
@@ -1936,18 +1945,6 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
 
         track_delegation_if_needed(func_name, args_dict, self.task)
 
-        structured_tool: CrewStructuredTool | None = None
-        if original_tool is not None:
-            for structured in self.tools or []:
-                if getattr(structured, "_original_tool", None) is original_tool:
-                    structured_tool = structured
-                    break
-        if structured_tool is None:
-            for structured in self.tools or []:
-                if sanitize_tool_name(structured.name) == func_name:
-                    structured_tool = structured
-                    break
-
         hook_blocked = False
         before_hook_context = ToolCallHookContext(
             tool_name=func_name,
@@ -1973,12 +1970,13 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
 
         if hook_blocked:
             result = f"Tool execution blocked by hook. Tool: {func_name}"
-        elif not from_cache and not max_usage_reached:
-            result = "Tool not found"
+            raw_tool_result = result
+        elif not from_cache and not max_usage_reached and output_tool is not None:
             if func_name in self._available_functions:
                 try:
                     tool_func = self._available_functions[func_name]
                     raw_result = tool_func(**args_dict)
+                    raw_tool_result = raw_result
 
                     # Add to cache after successful execution (before string conversion)
                     if self.tools_handler and self.tools_handler.cache:
@@ -1992,14 +1990,12 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
                                 tool=func_name, input=input_str, output=raw_result
                             )
 
-                    # Convert to string for message
-                    result = (
-                        str(raw_result)
-                        if not isinstance(raw_result, str)
-                        else raw_result
+                    result = format_native_tool_output_for_agent(
+                        output_tool, raw_result
                     )
                 except Exception as e:
                     result = f"Error executing tool: {e}"
+                    raw_tool_result = result
                     if self.task:
                         self.task.increment_tools_errors()
                     # Emit tool usage error event
@@ -2021,6 +2017,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
                 result = f"Tool '{func_name}' has reached its usage limit of {original_tool.max_usage_count} times and cannot be used anymore."
             else:
                 result = f"Tool '{func_name}' has reached its maximum usage limit and cannot be used anymore."
+            raw_tool_result = result
 
         # Execute after_tool_call hooks (even if blocked, to allow logging/monitoring)
         after_hook_context = ToolCallHookContext(
@@ -2031,6 +2028,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
             task=self.task,
             crew=self.crew,
             tool_result=result,
+            raw_tool_result=raw_tool_result,
         )
         after_hooks = get_after_tool_call_hooks()
         try:

lib/crewai/src/crewai/experimental/skills/cache.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 from datetime import datetime, timezone
 import json
 import logging
+import os
 from pathlib import Path
 import tarfile
 from typing import TypedDict
@@ -127,12 +128,36 @@ class SkillCacheManager:
 
 
 def _safe_extractall(tf: tarfile.TarFile, dest: Path) -> None:
-    """Path-traversal-safe extraction for Python < 3.12."""
+    """Path-traversal-safe extraction for Python versions without tar filters.
+
+    Validates both the member's own path and, for symlink/hardlink members,
+    the link target. Without the link-target check a malicious archive can
+    plant a symlink that escapes ``dest`` followed by a regular member written
+    through that link, escaping ``dest`` even though every member name resolves
+    inside it. This mirrors the protection that
+    ``tarfile.extractall(..., filter="data")`` provides when available.
+    """
     dest_resolved = dest.resolve()
     for member in tf.getmembers():
         member_path = (dest / member.name).resolve()
         if not member_path.is_relative_to(dest_resolved):
             raise ValueError(f"Blocked path traversal attempt: {member.name!r}")
+        if not (member.isfile() or member.isdir() or member.issym() or member.islnk()):
+            raise ValueError(f"Blocked unsupported tar member: {member.name!r}")
+        if member.issym() or member.islnk():
+            link_target = member.linkname
+            if os.path.isabs(link_target):
+                raise ValueError(
+                    f"Blocked link target escaping destination: "
+                    f"{member.name!r} -> {link_target!r}"
+                )
+            anchor = dest if member.islnk() else (dest / member.name).parent
+            resolved_target = (anchor / link_target).resolve()
+            if not resolved_target.is_relative_to(dest_resolved):
+                raise ValueError(
+                    f"Blocked link target escaping destination: "
+                    f"{member.name!r} -> {link_target!r}"
+                )
     tf.extractall(dest)  # noqa: S202
 
 

lib/crewai/src/crewai/flow/dsl/_listen.py

@@ -8,8 +8,8 @@ from crewai.flow.dsl._types import FlowMethodDecorator, FlowTrigger
 from crewai.flow.dsl._utils import (
     P,
     R,
+    _merge_flow_method_definition,
     _method_action,
-    _set_flow_method_definition,
 )
 from crewai.flow.flow_definition import FlowMethodDefinition
 from crewai.flow.flow_wrappers import ListenMethod
@@ -45,7 +45,7 @@ def listen(condition: FlowTrigger) -> FlowMethodDecorator:
     def decorator(func: Callable[P, R]) -> ListenMethod[P, R]:
         wrapper = ListenMethod(func)
 
-        _set_flow_method_definition(
+        _merge_flow_method_definition(
             wrapper,
             FlowMethodDefinition(
                 do=_method_action(func),

lib/crewai/src/crewai/flow/dsl/_router.py

@@ -19,8 +19,8 @@ from crewai.flow.dsl._types import FlowMethodDecorator, FlowTrigger
 from crewai.flow.dsl._utils import (
     P,
     R,
+    _merge_flow_method_definition,
     _method_action,
-    _set_flow_method_definition,
 )
 from crewai.flow.flow_definition import FlowMethodDefinition
 from crewai.flow.flow_wrappers import RouterMethod
@@ -95,7 +95,7 @@ def _normalize_router_emit(value: Sequence[Any] | str) -> list[str]:
 
 
 def router(
-    condition: FlowTrigger,
+    condition: FlowTrigger | None = None,
     *,
     emit: Sequence[str] | str | None = None,
 ) -> FlowMethodDecorator:
@@ -107,6 +107,7 @@ def router(
 
     Args:
         condition: Specifies when the router should execute. Can be:
+            - None: no listen trigger, used when stacking with @start() or @listen()
             - str: Route label or method name that triggers this router
             - FlowCondition: Result from or_() or and_(), including nested conditions
             - Flow method reference: A method whose completion triggers this router
@@ -146,14 +147,17 @@ def router(
         else:
             router_events = _get_router_return_events(func) or []
 
-        _set_flow_method_definition(
+        method_definition_kwargs: dict[str, Any] = {
+            "do": _method_action(func),
+            "router": True,
+            "emit": router_events or None,
+        }
+        if condition is not None:
+            method_definition_kwargs["listen"] = _to_definition_condition(condition)
+
+        _merge_flow_method_definition(
             wrapper,
-            FlowMethodDefinition(
-                do=_method_action(func),
-                listen=_to_definition_condition(condition),
-                router=True,
-                emit=router_events or None,
-            ),
+            FlowMethodDefinition(**method_definition_kwargs),
         )
         return wrapper
 

lib/crewai/src/crewai/flow/dsl/_start.py

@@ -8,8 +8,8 @@ from crewai.flow.dsl._types import FlowMethodDecorator, FlowTrigger
 from crewai.flow.dsl._utils import (
     P,
     R,
+    _merge_flow_method_definition,
     _method_action,
-    _set_flow_method_definition,
 )
 from crewai.flow.flow_definition import FlowMethodDefinition
 from crewai.flow.flow_wrappers import StartMethod
@@ -54,7 +54,7 @@ def start(
     def decorator(func: Callable[P, R]) -> StartMethod[P, R]:
         wrapper = StartMethod(func)
 
-        _set_flow_method_definition(
+        _merge_flow_method_definition(
             wrapper,
             FlowMethodDefinition(
                 do=_method_action(func),

lib/crewai/src/crewai/flow/dsl/_utils.py

@@ -106,6 +106,25 @@ def _get_flow_method_definition(method: Any) -> FlowMethodDefinition | None:
     return None
 
 
+def _merge_flow_method_definition(
+    wrapper: FlowMethod[P, R],
+    definition: FlowMethodDefinition,
+) -> None:
+    existing = _get_flow_method_definition(wrapper)
+    if existing is None:
+        _set_flow_method_definition(wrapper, definition)
+        return
+
+    updates = {
+        field_name: getattr(definition, field_name)
+        for field_name in definition.model_fields_set
+    }
+    _set_flow_method_definition(
+        wrapper,
+        existing.model_copy(deep=True, update=updates),
+    )
+
+
 def _is_json_serializable(value: Any) -> bool:
     try:
         json.dumps(value)

lib/crewai/src/crewai/flow/flow.py

@@ -24,9 +24,6 @@ from crewai.flow.runtime import (
     Flow as RuntimeFlow,
     FlowMeta,
     FlowState,
-    LockedDictProxy,
-    LockedListProxy,
-    StateProxy,
 )
 
 
@@ -42,9 +39,6 @@ __all__ = [
     "Flow",
     "FlowMeta",
     "FlowState",
-    "LockedDictProxy",
-    "LockedListProxy",
-    "StateProxy",
     "and_",
     "listen",
     "or_",

lib/crewai/src/crewai/flow/flow_definition.py

@@ -1,7 +1,7 @@
-"""Flow Structure: the serializable, language-agnostic Flow contract.
+"""Flow Definition: the serializable, declarative Flow contract.
 
-Defines :class:`FlowDefinition` and its sub-models — a static, textual
-(JSON/YAML) representation of a Flow: its methods, trigger conditions,
+Defines :class:`FlowDefinition` and its sub-models — a static declarative
+representation of a Flow: its methods, trigger conditions,
 state, and configuration. It is independent of the Python authoring
 layer that may have produced it and of the engine that runs it (see
 ``runtime``).
@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import json
 import logging
+from pathlib import Path
 import re
 from typing import Annotated, Any, Literal, TypeAlias, cast
 
@@ -18,6 +19,7 @@ from pydantic import (
     BaseModel,
     ConfigDict,
     Field,
+    PrivateAttr,
     field_serializer,
     model_validator,
 )
@@ -233,7 +235,7 @@ class FlowPersistenceDefinition(BaseModel):
 
     ``persistence`` may hold a live backend when the definition is built from
     a decorated class — the engine then persists through the exact instance
-    the user configured; the JSON/YAML projection degrades it to its
+    the user configured; the declarative projection degrades it to its
     serialized config.
     """
 
@@ -273,7 +275,7 @@ class FlowHumanFeedbackDefinition(BaseModel):
     """Static human feedback configuration.
 
     ``llm`` and ``provider`` may hold live Python objects when the definition
-    is built from a decorated class; the JSON/YAML projection degrades them to
+    is built from a decorated class; the declarative projection degrades them to
     a serialized config (``llm``) or a ``module:qualname`` ref (``provider``).
     """
 
@@ -406,10 +408,19 @@ class FlowCrewActionDefinition(BaseModel):
     )
 
     call: Literal["crew"] = Field(
-        description="Action discriminator. Use crew to run an inline Crew definition.",
+        description=(
+            "Action discriminator. Use crew to run an inline or referenced Crew "
+            "definition."
+        ),
         examples=["crew"],
     )
-    with_: CrewDefinition = Field(
+    from_declaration: str | None = Field(
+        default=None,
+        description="Path to a JSON/JSONC Crew declaration file or folder.",
+        examples=["crews/research_crew"],
+    )
+    with_: CrewDefinition | None = Field(
+        default=None,
         alias="with",
         description="Inline Crew definition to load and execute for this action.",
         examples=[
@@ -430,10 +441,26 @@ class FlowCrewActionDefinition(BaseModel):
                         "agent": "researcher",
                     }
                 ],
-                "inputs": {"topic": "${state.topic}"},
             }
         ],
     )
+    inputs: dict[str, ExpressionData] | None = Field(
+        default=None,
+        description=(
+            "Input overrides passed to the Crew. String values are evaluated as CEL "
+            "only when the trimmed value starts with ${ and ends with }; all other "
+            "values are literal."
+        ),
+        examples=[{"topic": "${state.topic}"}],
+    )
+
+    @model_validator(mode="after")
+    def _validate_crew_source(self) -> FlowCrewActionDefinition:
+        if bool(self.from_declaration) == (self.with_ is not None):
+            raise ValueError(
+                "crew action requires exactly one of from_declaration or with"
+            )
+        return self
 
 
 class FlowAgentActionDefinition(BaseModel):
@@ -684,10 +711,12 @@ class FlowDefinition(BaseModel):
         arbitrary_types_allowed=True,
     )
 
+    _source_path: Path | None = PrivateAttr(default=None)
+
     schema_: Literal["crewai.flow/v1"] = Field(
         default="crewai.flow/v1",
         alias="schema",
-        description="Flow Definition schema identifier and version.",
+        description="Declarative Flow schema identifier and version.",
         examples=["crewai.flow/v1"],
     )
     name: str = Field(
@@ -748,7 +777,7 @@ class FlowDefinition(BaseModel):
         return self
 
     def to_dict(self, *, exclude_none: bool = True) -> dict[str, Any]:
-        """Serialize the definition to a JSON/YAML-ready dictionary."""
+        """Serialize the definition to a declaration-ready dictionary."""
         return self.model_dump(by_alias=True, exclude_none=exclude_none, mode="json")
 
     def to_json(self, *, indent: int | None = 2, exclude_none: bool = True) -> str:
@@ -764,29 +793,66 @@ class FlowDefinition(BaseModel):
             allow_unicode=True,
         )
 
+    @property
+    def source_path(self) -> Path | None:
+        """Original definition file path, when loaded from a file."""
+        return self._source_path
+
+    @property
+    def source_dir(self) -> Path | None:
+        """Directory used to resolve relative paths in the definition."""
+        if self._source_path is None:
+            return None
+        return self._source_path.parent
+
     @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> FlowDefinition:
+    def from_dict(
+        cls, data: dict[str, Any], *, source_path: Path | None = None
+    ) -> FlowDefinition:
         """Load a definition from a dictionary."""
         definition = cls.model_validate(data)
+        if source_path is not None:
+            definition._source_path = source_path.expanduser().resolve()
         log_flow_definition_issues(definition)
         return definition
 
     @classmethod
-    def from_json(cls, data: str) -> FlowDefinition:
-        """Load a definition from JSON."""
-        return cls.from_dict(json.loads(data))
+    def from_declaration(
+        cls,
+        *,
+        contents: FlowDefinition | str | dict[str, Any] | None = None,
+        path: Path | str | None = None,
+    ) -> FlowDefinition:
+        """Load a declarative flow from contents or a file path."""
+        if isinstance(contents, cls):
+            return contents
 
-    @classmethod
-    def from_yaml(cls, data: str) -> FlowDefinition:
-        """Load a definition from YAML."""
-        loaded = yaml.safe_load(data) or {}
+        source_path: Path | None = None
+        if contents is None:
+            if path is None:
+                raise ValueError("Provide contents or path")
+            source_path = Path(path)
+            contents = source_path.expanduser().read_text(encoding="utf-8")
+
+        if isinstance(contents, dict):
+            return cls.from_dict(contents)
+
+        if not isinstance(contents, str):
+            raise TypeError("Flow declaration contents must be a string or dictionary")
+
+        if not contents.strip():
+            if source_path is not None:
+                raise ValueError(f"Flow declaration file is empty: {source_path}")
+            raise ValueError("Flow declaration contents are empty")
+
+        loaded = yaml.safe_load(contents)
         if not isinstance(loaded, dict):
-            raise ValueError("Flow definition YAML must contain a mapping")
-        return cls.from_dict(loaded)
+            raise ValueError("Flow declaration must contain a mapping")
+        return cls.from_dict(loaded, source_path=source_path)
 
     @classmethod
     def json_schema(cls) -> dict[str, Any]:
-        """Return the JSON Schema for the Flow Definition contract."""
+        """Return the JSON Schema for the declarative Flow contract."""
         return cls.model_json_schema(by_alias=True)
 
 
@@ -826,10 +892,16 @@ def _validate_action_cel(
         return
 
     if isinstance(action, FlowCrewActionDefinition):
-        Expression(cast(ExpressionData, action.with_.inputs)).validate_template(
-            allowed_roots=allowed_roots,
-            source=f"{path}.with.inputs",
-        )
+        if action.with_ is not None:
+            Expression(cast(ExpressionData, action.with_.inputs)).validate_template(
+                allowed_roots=allowed_roots,
+                source=f"{path}.with.inputs",
+            )
+        if action.inputs is not None:
+            Expression(cast(ExpressionData, action.inputs)).validate_template(
+                allowed_roots=allowed_roots,
+                source=f"{path}.inputs",
+            )
         return
 
     if isinstance(action, FlowAgentActionDefinition):
@@ -870,14 +942,6 @@ def _validate_action_cel(
 def log_flow_definition_issues(definition: FlowDefinition) -> None:
     for method_name, method in definition.methods.items():
         path = f"methods.{method_name}"
-        if method.router and not method.is_start and method.listen is None:
-            _log_flow_definition_issue(
-                definition.name,
-                code="router_without_trigger",
-                severity="error",
-                path=path,
-                message="router: true requires either start or listen",
-            )
         if method.emit and not method.router:
             _log_flow_definition_issue(
                 definition.name,

lib/crewai/src/crewai/flow/runtime/__init__.py

@@ -1,8 +1,8 @@
 """Flow Runtime: the engine that executes a Flow.
 
-Provides the ``Flow`` class (kickoff/resume/listener dispatch), the
-``FlowMeta`` metaclass, and the thread-safe state proxies. Flows
-authored with the Python DSL (see ``dsl``) are described by a Flow
+Provides the ``Flow`` class (kickoff/resume/listener dispatch) and the
+``FlowMeta`` metaclass. Flows authored with the Python DSL (see ``dsl``)
+are described by a Flow
 Structure (see ``flow_definition``) and executed here.
 """
 
@@ -11,12 +11,8 @@ from __future__ import annotations
 import asyncio
 from collections.abc import (
     Callable,
-    ItemsView,
-    Iterable,
     Iterator,
-    KeysView,
     Sequence,
-    ValuesView,
 )
 from concurrent.futures import Future, ThreadPoolExecutor
 import contextvars
@@ -25,6 +21,7 @@ from datetime import datetime
 import enum
 import inspect
 import logging
+from pathlib import Path
 import threading
 from typing import (
     TYPE_CHECKING,
@@ -34,10 +31,8 @@ from typing import (
     Generic,
     Literal,
     ParamSpec,
-    SupportsIndex,
     TypeVar,
     cast,
-    overload,
 )
 from uuid import uuid4
 
@@ -122,7 +117,6 @@ from crewai.flow.human_feedback import (
 from crewai.flow.input_provider import InputProvider
 from crewai.flow.persistence.base import FlowPersistence
 from crewai.flow.runtime._actions import FlowScriptExecutionDisabledError, build_action
-from crewai.flow.runtime._refs import resolve_instance_ref, resolve_ref
 from crewai.flow.types import (
     FlowExecutionData,
     FlowMethodName,
@@ -136,6 +130,7 @@ from crewai.state.checkpoint_config import (
     _coerce_checkpoint,
     apply_checkpoint,
 )
+from crewai.utilities.declarative_refs import InvalidRefError, resolve_ref
 
 
 if TYPE_CHECKING:
@@ -226,7 +221,12 @@ def _build_definition_state_model(
             pass
 
         model_class = StateWithId
-    return model_class(**kwargs)
+    try:
+        return model_class(**kwargs)
+    except ValidationError as e:
+        if any(error.get("type") != "missing" for error in e.errors()):
+            raise
+        return model_class.model_construct(**kwargs)
 
 
 def _iter_condition_events(condition: FlowDefinitionCondition) -> Iterator[str]:
@@ -283,6 +283,18 @@ def _resolve_persistence(value: Any) -> Any:
     return value
 
 
+def _resolve_instance_ref(ref: str, *, field: str) -> Any:
+    target = resolve_ref(ref, field=field)
+    if not inspect.isclass(target):
+        return target
+    try:
+        return target()
+    except Exception as e:
+        raise InvalidRefError(
+            f"cannot instantiate {field} ref {ref!r} without arguments: {e}"
+        ) from e
+
+
 def _serialize_persistence(value: Any) -> dict[str, Any] | None:
     if value is None:
         return None
@@ -298,7 +310,7 @@ def _validate_input_provider(value: Any) -> Any:
     if value is None or isinstance(value, InputProvider):
         return value
     if isinstance(value, str) and ":" in value:
-        resolved = resolve_instance_ref(value, field="input_provider")
+        resolved = _resolve_instance_ref(value, field="input_provider")
     else:
         from crewai.types.callback import _dotted_path_to_instance
 
@@ -365,304 +377,6 @@ R = TypeVar("R")
 F = TypeVar("F", bound=Callable[..., Any])
 
 
-class LockedListProxy(list, Generic[T]):  # type: ignore[type-arg]
-    """Thread-safe proxy for list operations.
-
-    Subclasses ``list`` so that ``isinstance(proxy, list)`` returns True,
-    which is required by libraries like LanceDB and Pydantic that do strict
-    type checks. All mutations go through the lock; reads delegate to the
-    underlying list.
-    """
-
-    def __init__(self, lst: list[T], lock: threading.Lock) -> None:
-        super().__init__()  # empty builtin list; all access goes through self._list
-        self._list = lst
-        self._lock = lock
-
-    def append(self, item: T) -> None:
-        with self._lock:
-            self._list.append(item)
-
-    def extend(self, items: Iterable[T]) -> None:
-        with self._lock:
-            self._list.extend(items)
-
-    def insert(self, index: SupportsIndex, item: T) -> None:
-        with self._lock:
-            self._list.insert(index, item)
-
-    def remove(self, item: T) -> None:
-        with self._lock:
-            self._list.remove(item)
-
-    def pop(self, index: SupportsIndex = -1) -> T:
-        with self._lock:
-            return self._list.pop(index)
-
-    def clear(self) -> None:
-        with self._lock:
-            self._list.clear()
-
-    @overload
-    def __setitem__(self, index: SupportsIndex, value: T) -> None: ...
-    @overload
-    def __setitem__(self, index: slice, value: Iterable[T]) -> None: ...
-    def __setitem__(self, index: Any, value: Any) -> None:
-        with self._lock:
-            self._list[index] = value
-
-    def __delitem__(self, index: SupportsIndex | slice) -> None:
-        with self._lock:
-            del self._list[index]
-
-    @overload
-    def __getitem__(self, index: SupportsIndex) -> T: ...
-    @overload
-    def __getitem__(self, index: slice) -> list[T]: ...
-    def __getitem__(self, index: Any) -> Any:
-        return self._list[index]
-
-    def __len__(self) -> int:
-        return len(self._list)
-
-    def __iter__(self) -> Iterator[T]:
-        return iter(self._list)
-
-    def __contains__(self, item: object) -> bool:
-        return item in self._list
-
-    def __repr__(self) -> str:
-        return repr(self._list)
-
-    def __bool__(self) -> bool:
-        return bool(self._list)
-
-    def index(
-        self, value: T, start: SupportsIndex = 0, stop: SupportsIndex | None = None
-    ) -> int:
-        if stop is None:
-            return self._list.index(value, start)
-        return self._list.index(value, start, stop)
-
-    def count(self, value: T) -> int:
-        return self._list.count(value)
-
-    def sort(self, *, key: Any = None, reverse: bool = False) -> None:
-        with self._lock:
-            self._list.sort(key=key, reverse=reverse)
-
-    def reverse(self) -> None:
-        with self._lock:
-            self._list.reverse()
-
-    def copy(self) -> list[T]:
-        return self._list.copy()
-
-    def __add__(self, other: list[T]) -> list[T]:  # type: ignore[override]
-        return self._list + other
-
-    def __radd__(self, other: list[T]) -> list[T]:
-        return other + self._list
-
-    def __iadd__(self, other: Iterable[T]) -> LockedListProxy[T]:  # type: ignore[override]
-        with self._lock:
-            self._list += list(other)
-        return self
-
-    def __mul__(self, n: SupportsIndex) -> list[T]:
-        return self._list * n
-
-    def __rmul__(self, n: SupportsIndex) -> list[T]:
-        return self._list * n
-
-    def __imul__(self, n: SupportsIndex) -> LockedListProxy[T]:
-        with self._lock:
-            self._list *= n
-        return self
-
-    def __reversed__(self) -> Iterator[T]:
-        return reversed(self._list)
-
-    def __eq__(self, other: object) -> bool:
-        """Compare based on the underlying list contents."""
-        if isinstance(other, LockedListProxy):
-            # Avoid deadlocks by acquiring locks in a consistent order.
-            first, second = (self, other) if id(self) <= id(other) else (other, self)
-            with first._lock:
-                with second._lock:
-                    return first._list == second._list
-        with self._lock:
-            return self._list == other
-
-    def __ne__(self, other: object) -> bool:
-        return not self.__eq__(other)
-
-
-class LockedDictProxy(dict, Generic[T]):  # type: ignore[type-arg]
-    """Thread-safe proxy for dict operations.
-
-    Subclasses ``dict`` so that ``isinstance(proxy, dict)`` returns True,
-    which is required by libraries like Pydantic that do strict type checks.
-    All mutations go through the lock; reads delegate to the underlying dict.
-    """
-
-    def __init__(self, d: dict[str, T], lock: threading.Lock) -> None:
-        super().__init__()  # empty builtin dict; all access goes through self._dict
-        self._dict = d
-        self._lock = lock
-
-    def __setitem__(self, key: str, value: T) -> None:
-        with self._lock:
-            self._dict[key] = value
-
-    def __delitem__(self, key: str) -> None:
-        with self._lock:
-            del self._dict[key]
-
-    def pop(self, key: str, *default: T) -> T:  # type: ignore[override]
-        with self._lock:
-            return self._dict.pop(key, *default)
-
-    def update(self, other: dict[str, T]) -> None:  # type: ignore[override]
-        with self._lock:
-            self._dict.update(other)
-
-    def clear(self) -> None:
-        with self._lock:
-            self._dict.clear()
-
-    def setdefault(self, key: str, default: T) -> T:  # type: ignore[override]
-        with self._lock:
-            return self._dict.setdefault(key, default)
-
-    def __getitem__(self, key: str) -> T:
-        return self._dict[key]
-
-    def __len__(self) -> int:
-        return len(self._dict)
-
-    def __iter__(self) -> Iterator[str]:
-        return iter(self._dict)
-
-    def __contains__(self, key: object) -> bool:
-        return key in self._dict
-
-    def keys(self) -> KeysView[str]:  # type: ignore[override]
-        return self._dict.keys()
-
-    def values(self) -> ValuesView[T]:  # type: ignore[override]
-        return self._dict.values()
-
-    def items(self) -> ItemsView[str, T]:  # type: ignore[override]
-        return self._dict.items()
-
-    def get(self, key: str, default: T | None = None) -> T | None:  # type: ignore[override]
-        return self._dict.get(key, default)
-
-    def __repr__(self) -> str:
-        return repr(self._dict)
-
-    def __bool__(self) -> bool:
-        return bool(self._dict)
-
-    def copy(self) -> dict[str, T]:
-        return self._dict.copy()
-
-    def __or__(self, other: dict[str, T]) -> dict[str, T]:  # type: ignore[override]
-        return self._dict | other
-
-    def __ror__(self, other: dict[str, T]) -> dict[str, T]:  # type: ignore[override]
-        return other | self._dict
-
-    def __ior__(self, other: dict[str, T]) -> LockedDictProxy[T]:  # type: ignore[override]
-        with self._lock:
-            self._dict |= other
-        return self
-
-    def __reversed__(self) -> Iterator[str]:
-        return reversed(self._dict)
-
-    def __eq__(self, other: object) -> bool:
-        """Compare based on the underlying dict contents."""
-        if isinstance(other, LockedDictProxy):
-            # Avoid deadlocks by acquiring locks in a consistent order.
-            first, second = (self, other) if id(self) <= id(other) else (other, self)
-            with first._lock:
-                with second._lock:
-                    return first._dict == second._dict
-        with self._lock:
-            return self._dict == other
-
-    def __ne__(self, other: object) -> bool:
-        return not self.__eq__(other)
-
-
-class StateProxy(Generic[T]):
-    """Proxy that provides thread-safe access to flow state.
-
-    Wraps state objects (dict or BaseModel) and uses a lock for all write
-    operations to prevent race conditions when parallel listeners modify state.
-    """
-
-    __slots__ = ("_proxy_lock", "_proxy_state")
-
-    def __init__(self, state: T, lock: threading.Lock) -> None:
-        object.__setattr__(self, "_proxy_state", state)
-        object.__setattr__(self, "_proxy_lock", lock)
-
-    def __getattr__(self, name: str) -> Any:
-        value = getattr(object.__getattribute__(self, "_proxy_state"), name)
-        lock = object.__getattribute__(self, "_proxy_lock")
-        if isinstance(value, list):
-            return LockedListProxy(value, lock)
-        if isinstance(value, dict):
-            return LockedDictProxy(value, lock)
-        return value
-
-    def __setattr__(self, name: str, value: Any) -> None:
-        if name in ("_proxy_state", "_proxy_lock"):
-            object.__setattr__(self, name, value)
-        else:
-            if isinstance(value, LockedListProxy):
-                value = value._list
-            elif isinstance(value, LockedDictProxy):
-                value = value._dict
-            with object.__getattribute__(self, "_proxy_lock"):
-                setattr(object.__getattribute__(self, "_proxy_state"), name, value)
-
-    def __getitem__(self, key: str) -> Any:
-        return object.__getattribute__(self, "_proxy_state")[key]
-
-    def __setitem__(self, key: str, value: Any) -> None:
-        with object.__getattribute__(self, "_proxy_lock"):
-            object.__getattribute__(self, "_proxy_state")[key] = value
-
-    def __delitem__(self, key: str) -> None:
-        with object.__getattribute__(self, "_proxy_lock"):
-            del object.__getattribute__(self, "_proxy_state")[key]
-
-    def __contains__(self, key: str) -> bool:
-        return key in object.__getattribute__(self, "_proxy_state")
-
-    def __repr__(self) -> str:
-        return repr(object.__getattribute__(self, "_proxy_state"))
-
-    def _unwrap(self) -> T:
-        """Return the underlying state object."""
-        return cast(T, object.__getattribute__(self, "_proxy_state"))
-
-    def model_dump(self, *args: Any, **kwargs: Any) -> dict[str, Any]:
-        """Return state as a dictionary.
-
-        Works for both dict and BaseModel underlying states.
-        """
-        state = object.__getattribute__(self, "_proxy_state")
-        if isinstance(state, dict):
-            return state
-        result: dict[str, Any] = state.model_dump(*args, **kwargs)
-        return result
-
-
 class FlowMeta(ModelMetaclass):
     def __new__(
         mcs,
@@ -769,6 +483,21 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
     @classmethod
     def from_definition(cls, definition: FlowDefinition, **kwargs: Any) -> Flow[Any]:
         """Build a runnable Flow directly from a definition; no subclass required."""
+        return cls.from_declaration(contents=definition, **kwargs)
+
+    @classmethod
+    def from_declaration(
+        cls,
+        *,
+        contents: FlowDefinition | str | dict[str, Any] | None = None,
+        path: Path | str | None = None,
+        **kwargs: Any,
+    ) -> Flow[Any]:
+        """Build a runnable declarative flow from contents or a file path."""
+        definition = FlowDefinition.from_declaration(
+            contents=contents,
+            path=path,
+        )
         return cls.model_validate(
             {**definition.config.model_dump(), **kwargs},
             context={"flow_definition": definition},
@@ -992,7 +721,6 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
     )
     _method_outputs: list[Any] = PrivateAttr(default_factory=list)
     _definition: FlowDefinition = PrivateAttr()
-    _state_lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)
     _or_listeners_lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)
     _completed_methods: set[FlowMethodName] = PrivateAttr(default_factory=set)
     _method_call_counts: dict[FlowMethodName, int] = PrivateAttr(default_factory=dict)
@@ -1914,7 +1642,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
 
     @property
     def state(self) -> T:
-        return StateProxy(self._state, self._state_lock)  # type: ignore[return-value]
+        return cast(T, self._state)
 
     @property
     def method_outputs(self) -> list[Any]:
@@ -2455,11 +2183,6 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
                     object.__setattr__(
                         self, "_deferred_flow_started_event_id", started_event.event_id
                     )
-                if not self.suppress_flow_events:
-                    self._log_flow_event(
-                        f"Flow started with ID: {self.flow_id}", color="bold magenta"
-                    )
-
             # After FlowStarted: env events must not pre-empt trace batch init
             # with implicit "crew" execution_type.
             get_env_context()
@@ -3007,6 +2730,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
         """
         # First, handle routers repeatedly until no router triggers anymore
         router_results = []
+        router_result_payloads: dict[str, Any] = {}
         router_result_to_feedback: dict[
             str, Any
         ] = {}  # Map outcome -> HumanFeedbackResult
@@ -3044,6 +2768,11 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
                 router_result_str = str(router_result)
                 router_result_event = FlowMethodName(router_result_str)
                 router_results.append(router_result_event)
+                router_result_payloads[router_result_str] = (
+                    self.last_human_feedback
+                    if self.last_human_feedback is not None
+                    else router_result
+                )
 
                 if self.last_human_feedback is not None:
                     router_result_to_feedback[router_result_str] = (
@@ -3064,7 +2793,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
                     current_trigger, router_only=False
                 )
                 if listeners_triggered:
-                    listener_result = router_result_to_feedback.get(
+                    listener_result = router_result_payloads.get(
                         str(current_trigger), result
                     )
                     racing_group = self._get_racing_group_for_listeners(
@@ -3583,7 +3312,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
     ) -> Any:
         provider = feedback_definition.provider
         if isinstance(provider, str):
-            provider = resolve_instance_ref(provider, field="human_feedback.provider")
+            provider = _resolve_instance_ref(provider, field="human_feedback.provider")
         if provider is None:
             from crewai.flow.flow_config import flow_config
 

lib/crewai/src/crewai/flow/runtime/_actions.py

@@ -8,6 +8,7 @@ from collections.abc import Awaitable, Callable
 import contextvars
 import inspect
 import os
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, Protocol, cast
 
 from crewai.flow.expressions import Expression, ExpressionData
@@ -23,7 +24,11 @@ from crewai.flow.flow_definition import (
     FlowToolActionDefinition,
 )
 from crewai.flow.runtime._outputs import outputs_by_name
-from crewai.flow.runtime._refs import InvalidRefError, resolve_ref
+from crewai.utilities.declarative_refs import (
+    InvalidRefError,
+    resolve_class_ref,
+    resolve_ref,
+)
 
 
 if TYPE_CHECKING:
@@ -102,16 +107,17 @@ class ToolAction:
         )
 
     def _build_tool(self) -> Any:
-        target = resolve_ref(self.definition.ref, field="do")
         from crewai.tools import BaseTool
 
-        if not (inspect.isclass(target) and issubclass(target, BaseTool)):
-            raise InvalidRefError(
-                f"invalid tool ref {self.definition.ref!r}; expected a BaseTool class"
-            )
-
+        tool_cls = cast(
+            Callable[[], BaseTool],
+            resolve_class_ref(
+                self.definition.ref,
+                field="do",
+                base_class=BaseTool,
+            ),
+        )
         try:
-            tool_cls = cast(Callable[[], BaseTool], target)
             return tool_cls()
         except Exception as e:
             raise InvalidRefError(
@@ -128,16 +134,34 @@ class CrewAction:
         self.definition = definition
 
     async def run(self, *_args: Any, **kwargs: Any) -> Any:
-        from crewai.project.crew_loader import load_crew_from_definition
+        from crewai.project.crew_loader import load_crew, load_crew_from_definition
 
         local_context = _pop_local_context(kwargs)
-        crew_definition = self.definition.with_
+        if self.definition.from_declaration is not None:
+            crew, default_inputs = load_crew(
+                _resolve_crew_declaration(
+                    self.definition.from_declaration,
+                    base_dir=self.flow._definition.source_dir,
+                )
+            )
+            input_template = {**default_inputs, **(self.definition.inputs or {})}
+        else:
+            crew_definition = self.definition.with_
+            if crew_definition is None:
+                raise ValueError(
+                    "crew action requires exactly one of from_declaration or with"
+                )
+            input_template = {
+                **crew_definition.inputs,
+                **(self.definition.inputs or {}),
+            }
+            crew, _ = load_crew_from_definition(crew_definition, source="crew action")
+
         inputs = Expression.from_flow(
-            cast(ExpressionData, crew_definition.inputs),
+            cast(ExpressionData, input_template),
             self.flow,
             local_context=local_context,
         ).render_template()
-        crew, _ = load_crew_from_definition(crew_definition, source="crew action")
         return await crew.kickoff_async(inputs=inputs)
 
 
@@ -359,3 +383,29 @@ def _pop_local_context(kwargs: dict[str, Any]) -> LocalContext | None:
     if not isinstance(local_context, dict):
         raise TypeError("flow definition local context must be a mapping")
     return cast(LocalContext, local_context)
+
+
+def _resolve_crew_declaration(
+    from_declaration: str, *, base_dir: Path | None = None
+) -> Path:
+    path = Path(from_declaration).expanduser()
+    if base_dir is not None:
+        resolved_base_dir = base_dir.expanduser().resolve()
+        if not path.is_absolute():
+            path = resolved_base_dir / path
+        resolved_path = path.resolve()
+        if not resolved_path.is_relative_to(resolved_base_dir):
+            raise ValueError(
+                "crew declaration path must be within the flow definition directory"
+            )
+        path = resolved_path
+
+    if not path.is_dir():
+        return path
+
+    for name in ("crew.jsonc", "crew.json"):
+        candidate = path / name
+        if candidate.is_file():
+            return candidate
+
+    return path / "crew.jsonc"

lib/crewai/src/crewai/flow/runtime/_refs.py

@@ -1,38 +0,0 @@
-"""Resolution of ``module:qualname`` refs into live Python objects."""
-
-from __future__ import annotations
-
-import importlib
-import inspect
-from operator import attrgetter
-from typing import Any
-
-
-class InvalidRefError(ValueError):
-    """A definition ref that cannot be resolved to a live object."""
-
-
-def resolve_ref(ref: str, *, field: str) -> Any:
-    """Import the object a definition's `module:qualname` ref points to."""
-    module_name, _, qualname = ref.partition(":")
-    if "<" in ref or not module_name or not qualname:
-        raise InvalidRefError(
-            f"invalid {field} ref {ref!r}; expected 'module:qualname'"
-        )
-    try:
-        return attrgetter(qualname)(importlib.import_module(module_name))
-    except (ImportError, AttributeError) as e:
-        raise InvalidRefError(f"unresolvable {field} ref {ref!r}") from e
-
-
-def resolve_instance_ref(ref: str, *, field: str) -> Any:
-    """Resolve a ref, auto-instantiating a no-arg class into an instance."""
-    target = resolve_ref(ref, field=field)
-    if not inspect.isclass(target):
-        return target
-    try:
-        return target()
-    except Exception as e:
-        raise InvalidRefError(
-            f"cannot instantiate {field} ref {ref!r} without arguments: {e}"
-        ) from e

lib/crewai/src/crewai/hooks/tool_hooks.py

@@ -40,6 +40,8 @@ class ToolCallHookContext:
         crew: Crew instance (may be None)
         tool_result: Tool execution result (only set for after_tool_call hooks).
             Can be modified by returning a new string from after_tool_call hook.
+        raw_tool_result: Raw Python tool execution result (only set for
+            after_tool_call hooks). This is not modified by after hooks.
     """
 
     def __init__(
@@ -51,6 +53,7 @@ class ToolCallHookContext:
         task: Task | None = None,
         crew: Crew | None = None,
         tool_result: str | None = None,
+        raw_tool_result: Any | None = None,
     ) -> None:
         """Initialize tool call hook context.
 
@@ -62,6 +65,7 @@ class ToolCallHookContext:
             task: Optional current task
             crew: Optional crew instance
             tool_result: Optional tool result (for after hooks)
+            raw_tool_result: Optional raw tool result (for after hooks)
         """
         self.tool_name = tool_name
         self.tool_input = tool_input
@@ -70,6 +74,7 @@ class ToolCallHookContext:
         self.task = task
         self.crew = crew
         self.tool_result = tool_result
+        self.raw_tool_result = raw_tool_result
 
     def request_human_input(
         self,

lib/crewai/src/crewai/project/json_loader.py

@@ -16,6 +16,8 @@ from urllib.parse import unquote, urlparse
 
 from pydantic import BaseModel, ValidationError
 
+from crewai.utilities.declarative_refs import InvalidRefError, resolve_class_ref
+
 
 logger = logging.getLogger(__name__)
 
@@ -1820,6 +1822,9 @@ def _resolve_tools(tool_defs: list[Any], project_root: Path | None = None) -> li
         if tool_def.startswith("custom:"):
             tools.append(_resolve_custom_tool(tool_def[7:], project_root=project_root))
             continue
+        if ":" in tool_def:
+            tools.append(_instantiate_tool_import_ref(tool_def))
+            continue
         try:
             tool_cls = _find_tool_class(tool_def)
         except Exception as e:
@@ -1827,8 +1832,10 @@ def _resolve_tools(tool_defs: list[Any], project_root: Path | None = None) -> li
         if tool_cls is None:
             raise JSONProjectError(
                 f"Unknown tool '{tool_def}'. Tool names must match a class from "
-                f"the 'crewai_tools' package (e.g. 'SerperDevTool') or use the "
-                f"'custom:<name>' prefix for a tool defined in tools/<name>.py."
+                f"the 'crewai_tools' package (e.g. 'SerperDevTool'), use a "
+                f"'module:ClassName' import ref (e.g. 'crewai_tools:SerperDevTool'), "
+                f"or use the 'custom:<name>' prefix for a tool defined in "
+                f"tools/<name>.py."
             )
         try:
             tools.append(tool_cls())
@@ -1839,6 +1846,32 @@ def _resolve_tools(tool_defs: list[Any], project_root: Path | None = None) -> li
     return tools
 
 
+def _instantiate_tool_import_ref(ref: str) -> Any:
+    from crewai.tools import BaseTool
+
+    try:
+        tool_cls = cast(
+            Callable[[], BaseTool],
+            resolve_class_ref(ref, field="tool", base_class=BaseTool),
+        )
+    except InvalidRefError as e:
+        message = str(e)
+        if (
+            message.startswith("unresolvable ")
+            or "expected 'module:qualname'" in message
+        ):
+            raise JSONProjectError(str(e)) from e
+        raise JSONProjectError(
+            f"invalid tool ref {ref!r}; expected a BaseTool class"
+        ) from e
+    try:
+        return tool_cls()
+    except Exception as e:
+        raise JSONProjectError(
+            f"cannot instantiate tool ref {ref!r} without arguments: {e}"
+        ) from e
+
+
 _tool_class_cache: dict[str, type | None] = {}
 
 

lib/crewai/src/crewai/tools/base_tool.py

@@ -33,6 +33,8 @@ from typing_extensions import TypeIs
 from crewai.tools.structured_tool import (
     CrewStructuredTool,
     _deserialize_schema,
+    _format_tool_output_for_agent,
+    _infer_result_schema_from_callable,
     _serialize_schema,
     build_schema_hint,
 )
@@ -149,6 +151,11 @@ class BaseTool(BaseModel, ABC):
         validate_default=True,
         description="The schema for the arguments that the tool accepts.",
     )
+    result_schema: type[PydanticBaseModel] | None = Field(
+        default=None,
+        validate_default=True,
+        description="The schema for the output that the tool returns.",
+    )
 
     @field_serializer("args_schema", when_used="json")
     def _serialize_args_schema(
@@ -156,6 +163,12 @@ class BaseTool(BaseModel, ABC):
     ) -> dict[str, Any] | None:
         return _serialize_schema(schema)
 
+    @field_serializer("result_schema", when_used="json")
+    def _serialize_result_schema(
+        self, schema: type[PydanticBaseModel] | None
+    ) -> dict[str, Any] | None:
+        return _serialize_schema(schema)
+
     description_updated: bool = Field(
         default=False, description="Flag to check if the description has been updated."
     )
@@ -233,6 +246,17 @@ class BaseTool(BaseModel, ABC):
 
         return create_model(f"{cls.__name__}Schema", **fields)
 
+    @field_validator("result_schema", mode="before")
+    @classmethod
+    def _default_result_schema(
+        cls, v: type[PydanticBaseModel] | dict[str, Any] | None
+    ) -> type[PydanticBaseModel] | None:
+        if isinstance(v, dict):
+            return _deserialize_schema(v)
+        if v is not None:
+            return v
+        return _infer_result_schema_from_callable(cls._run)
+
     @field_validator("max_usage_count", mode="before")
     @classmethod
     def validate_max_usage_count(cls, v: int | None) -> int | None:
@@ -340,6 +364,10 @@ class BaseTool(BaseModel, ABC):
             "Override _arun for async support or use run() for sync execution."
         )
 
+    def format_output_for_agent(self, raw_result: Any) -> str:
+        """Format a raw tool result into the string representation sent to an agent."""
+        return _format_tool_output_for_agent(self, raw_result)
+
     def reset_usage_count(self) -> None:
         """Reset the current usage count to zero."""
         self.current_usage_count = 0
@@ -369,6 +397,7 @@ class BaseTool(BaseModel, ABC):
             name=self.name,
             description=self.description,
             args_schema=self.args_schema,
+            result_schema=self.result_schema,
             func=self._run,
             result_as_answer=self.result_as_answer,
             max_usage_count=self.max_usage_count,
@@ -390,6 +419,9 @@ class BaseTool(BaseModel, ABC):
             raise ValueError("The provided tool must have a callable 'func' attribute.")
 
         args_schema = getattr(tool, "args_schema", None)
+        result_schema = getattr(tool, "result_schema", None)
+        if result_schema is None:
+            result_schema = _infer_result_schema_from_callable(tool.func)
 
         if args_schema is None:
             func_signature = signature(tool.func)
@@ -420,6 +452,7 @@ class BaseTool(BaseModel, ABC):
             description=getattr(tool, "description", ""),
             func=tool.func,
             args_schema=args_schema,
+            result_schema=result_schema,
         )
 
     def _set_args_schema(self) -> None:
@@ -568,6 +601,9 @@ class Tool(BaseTool, Generic[P, R]):
             raise ValueError("The provided tool must have a callable 'func' attribute.")
 
         args_schema = getattr(tool, "args_schema", None)
+        result_schema = getattr(tool, "result_schema", None)
+        if result_schema is None:
+            result_schema = _infer_result_schema_from_callable(tool.func)
 
         if args_schema is None:
             func_signature = signature(tool.func)
@@ -598,6 +634,7 @@ class Tool(BaseTool, Generic[P, R]):
             description=getattr(tool, "description", ""),
             func=tool.func,
             args_schema=args_schema,
+            result_schema=result_schema,
         )
 
 
@@ -621,6 +658,7 @@ def tool(
     name: str,
     /,
     *,
+    result_schema: type[BaseModel] | None = ...,
     result_as_answer: bool = ...,
     max_usage_count: int | None = ...,
 ) -> Callable[[Callable[P2, R2]], Tool[P2, R2]]: ...
@@ -629,6 +667,7 @@ def tool(
 @overload
 def tool(
     *,
+    result_schema: type[BaseModel] | None = ...,
     result_as_answer: bool = ...,
     max_usage_count: int | None = ...,
 ) -> Callable[[Callable[P2, R2]], Tool[P2, R2]]: ...
@@ -636,6 +675,7 @@ def tool(
 
 def tool(
     *args: Callable[P2, R2] | str,
+    result_schema: type[BaseModel] | None = None,
     result_as_answer: bool = False,
     max_usage_count: int | None = None,
 ) -> Tool[P2, R2] | Callable[[Callable[P2, R2]], Tool[P2, R2]]:
@@ -649,6 +689,7 @@ def tool(
     Args:
         *args: Either the function to decorate or a custom tool name.
         result_as_answer: If True, the tool result becomes the final agent answer.
+        result_schema: Optional schema for the output that the tool returns.
         max_usage_count: Maximum times this tool can be used. None means unlimited.
 
     Returns:
@@ -690,12 +731,16 @@ def tool(
 
             class_name = "".join(tool_name.split()).title()
             args_schema = create_model(class_name, **fields)
+            resolved_result_schema = (
+                result_schema or _infer_result_schema_from_callable(f)
+            )
 
             return Tool(
                 name=tool_name,
                 description=f.__doc__,
                 func=f,
                 args_schema=args_schema,
+                result_schema=resolved_result_schema,
                 result_as_answer=result_as_answer,
                 max_usage_count=max_usage_count,
                 current_usage_count=0,

lib/crewai/src/crewai/tools/structured_tool.py

@@ -5,7 +5,8 @@ from collections.abc import Callable
 import inspect
 import json
 import textwrap
-from typing import TYPE_CHECKING, Annotated, Any, get_type_hints
+from typing import TYPE_CHECKING, Annotated, Any, cast, get_type_hints
+import warnings
 
 from pydantic import (
     BaseModel,
@@ -36,6 +37,52 @@ def _deserialize_schema(v: Any) -> type[BaseModel] | None:
     return None
 
 
+def _infer_result_schema_from_callable(
+    func: Callable[..., Any],
+) -> type[BaseModel] | None:
+    try:
+        return_annotation = get_type_hints(func).get("return", inspect.Signature.empty)
+    except Exception:
+        return_annotation = inspect.signature(func).return_annotation
+
+    if isinstance(return_annotation, type) and issubclass(return_annotation, BaseModel):
+        return return_annotation
+
+    return None
+
+
+def _format_tool_output_for_agent(tool: Any, raw_result: Any) -> str:
+    original_tool = getattr(tool, "_original_tool", None)
+    if original_tool is not None:
+        return cast(str, original_tool.format_output_for_agent(raw_result))
+
+    result_schema = getattr(tool, "result_schema", None)
+    if not (isinstance(result_schema, type) and issubclass(result_schema, BaseModel)):
+        return str(raw_result)
+
+    try:
+        validation_input = raw_result
+        if isinstance(raw_result, BaseModel) and not isinstance(
+            raw_result, result_schema
+        ):
+            validation_input = raw_result.model_dump()
+
+        validated = result_schema.model_validate(validation_input)
+        return validated.model_dump_json()
+    except Exception as exc:
+        warnings.warn(
+            (
+                f"Failed to validate or serialize output from tool "
+                f"'{getattr(tool, 'name', '<unknown>')}' using result_schema "
+                f"'{result_schema.__name__}': {exc.__class__.__name__}. "
+                "Falling back to str(raw_result)."
+            ),
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return str(raw_result)
+
+
 if TYPE_CHECKING:
     pass
 
@@ -81,6 +128,11 @@ class CrewStructuredTool(BaseModel):
         BeforeValidator(_deserialize_schema),
         PlainSerializer(_serialize_schema),
     ] = Field(default=None)
+    result_schema: Annotated[
+        type[BaseModel] | None,
+        BeforeValidator(_deserialize_schema),
+        PlainSerializer(_serialize_schema),
+    ] = Field(default=None)
     func: Any = Field(default=None, exclude=True)
     result_as_answer: bool = Field(default=False)
     max_usage_count: int | None = Field(default=None)
@@ -103,6 +155,7 @@ class CrewStructuredTool(BaseModel):
         description: str | None = None,
         return_direct: bool = False,
         args_schema: type[BaseModel] | None = None,
+        result_schema: type[BaseModel] | None = None,
         infer_schema: bool = True,
         **kwargs: Any,
     ) -> CrewStructuredTool:
@@ -114,6 +167,7 @@ class CrewStructuredTool(BaseModel):
             description: The description of the tool. Defaults to the function docstring
             return_direct: Whether to return the output directly
             args_schema: Optional schema for the function arguments
+            result_schema: Optional schema for the function output
             infer_schema: Whether to infer the schema from the function signature
             **kwargs: Additional arguments to pass to the tool
 
@@ -149,10 +203,16 @@ class CrewStructuredTool(BaseModel):
             name=name,
             description=description,
             args_schema=schema,
+            result_schema=result_schema or _infer_result_schema_from_callable(func),
             func=func,
             result_as_answer=return_direct,
+            **kwargs,
         )
 
+    def format_output_for_agent(self, raw_result: Any) -> str:
+        """Format a raw tool result into the string representation sent to an agent."""
+        return _format_tool_output_for_agent(self, raw_result)
+
     @staticmethod
     def _create_schema_from_function(
         name: str,

lib/crewai/src/crewai/tools/tool_usage.py

@@ -62,6 +62,9 @@ OPENAI_BIGGER_MODELS: list[
 ]
 
 
+_RAW_RESULT_UNSET = object()
+
+
 class ToolUsageError(Exception):
     """Exception raised for errors in the tool usage."""
 
@@ -106,6 +109,7 @@ class ToolUsage:
         self.action = action
         self.function_calling_llm = function_calling_llm
         self.fingerprint_context = fingerprint_context or {}
+        self.last_raw_result: Any = _RAW_RESULT_UNSET
 
         if (
             self.function_calling_llm
@@ -120,6 +124,11 @@ class ToolUsage:
         """Parse the tool string and return the tool calling."""
         return self._tool_calling(tool_string)
 
+    def get_last_raw_result(self, fallback: Any) -> Any:
+        if self.last_raw_result is _RAW_RESULT_UNSET:
+            return fallback
+        return self.last_raw_result
+
     def use(
         self, calling: ToolCalling | InstructorToolCalling, tool_string: str
     ) -> str:
@@ -231,6 +240,7 @@ class ToolUsage:
                 result = I18N_DEFAULT.errors("task_repeated_usage").format(
                     tool_names=self.tools_names
                 )
+                self.last_raw_result = result
                 self._telemetry.tool_repeated_usage(
                     llm=self.function_calling_llm,
                     tool_name=sanitize_tool_name(tool.name),
@@ -298,6 +308,7 @@ class ToolUsage:
             )
             if usage_limit_error:
                 result = usage_limit_error
+                self.last_raw_result = result
                 self._telemetry.tool_usage_error(llm=self.function_calling_llm)
                 result = self._format_result(result=result)
             elif result is None:
@@ -359,7 +370,10 @@ class ToolUsage:
                         tool_name=sanitize_tool_name(tool.name),
                         attempts=self._run_attempts,
                     )
-                    result = self._format_result(result=result)
+                    self.last_raw_result = result
+                    result = self._format_result(
+                        result=tool.format_output_for_agent(result)
+                    )
                     data = {
                         "result": result,
                         "tool_name": sanitize_tool_name(tool.name),
@@ -421,6 +435,7 @@ class ToolUsage:
                         result = ToolUsageError(
                             f"\n{error_message}.\nMoving on then. {I18N_DEFAULT.slice('format').format(tool_names=self.tools_names)}"
                         ).message
+                        self.last_raw_result = result
                         if self.task:
                             self.task.increment_tools_errors()
                         if self.agent and self.agent.verbose:
@@ -430,7 +445,10 @@ class ToolUsage:
                             self.task.increment_tools_errors()
                         should_retry = True
             else:
-                result = self._format_result(result=result)
+                self.last_raw_result = result
+                result = self._format_result(
+                    result=tool.format_output_for_agent(result)
+                )
 
         finally:
             if started_event_emitted and not error_event_emitted:
@@ -460,6 +478,7 @@ class ToolUsage:
                 result = I18N_DEFAULT.errors("task_repeated_usage").format(
                     tool_names=self.tools_names
                 )
+                self.last_raw_result = result
                 self._telemetry.tool_repeated_usage(
                     llm=self.function_calling_llm,
                     tool_name=sanitize_tool_name(tool.name),
@@ -529,6 +548,7 @@ class ToolUsage:
             )
             if usage_limit_error:
                 result = usage_limit_error
+                self.last_raw_result = result
                 self._telemetry.tool_usage_error(llm=self.function_calling_llm)
                 result = self._format_result(result=result)
             elif result is None:
@@ -590,7 +610,10 @@ class ToolUsage:
                         tool_name=sanitize_tool_name(tool.name),
                         attempts=self._run_attempts,
                     )
-                    result = self._format_result(result=result)
+                    self.last_raw_result = result
+                    result = self._format_result(
+                        result=tool.format_output_for_agent(result)
+                    )
                     data = {
                         "result": result,
                         "tool_name": sanitize_tool_name(tool.name),
@@ -652,6 +675,7 @@ class ToolUsage:
                         result = ToolUsageError(
                             f"\n{error_message}.\nMoving on then. {I18N_DEFAULT.slice('format').format(tool_names=self.tools_names)}"
                         ).message
+                        self.last_raw_result = result
                         if self.task:
                             self.task.increment_tools_errors()
                         if self.agent and self.agent.verbose:
@@ -661,7 +685,10 @@ class ToolUsage:
                             self.task.increment_tools_errors()
                         should_retry = True
             else:
-                result = self._format_result(result=result)
+                self.last_raw_result = result
+                result = self._format_result(
+                    result=tool.format_output_for_agent(result)
+                )
 
         finally:
             if started_event_emitted and not error_event_emitted:

lib/crewai/src/crewai/utilities/agent_utils.py

@@ -1383,6 +1383,19 @@ class NativeToolCallResult:
     tool_message: LLMMessage = field(default_factory=dict)  # type: ignore[assignment]
 
 
+def format_native_tool_output_for_agent(tool: Any, raw_result: Any) -> str:
+    """Format native tool output when a tool explicitly defines a formatter."""
+    formatter = inspect.getattr_static(tool, "format_output_for_agent", None)
+    if formatter is None:
+        return str(raw_result)
+
+    runtime_formatter = getattr(tool, "format_output_for_agent", None)
+    if not callable(runtime_formatter):
+        return str(raw_result)
+
+    return str(runtime_formatter(raw_result))
+
+
 def execute_single_native_tool_call(
     tool_call: Any,
     *,
@@ -1456,18 +1469,24 @@ def execute_single_native_tool_call(
             original_tool = tool
             break
 
+    structured_tool: CrewStructuredTool | None = None
+    for structured in structured_tools or []:
+        if sanitize_tool_name(structured.name) == func_name:
+            structured_tool = structured
+            break
+
+    output_tool = original_tool or structured_tool
+
     from_cache = False
     input_str = json.dumps(args_dict) if args_dict else ""
     result = "Tool not found"
+    raw_tool_result: Any = result
 
-    if tools_handler and tools_handler.cache:
+    if tools_handler and tools_handler.cache and output_tool is not None:
         cached_result = tools_handler.cache.read(tool=func_name, input=input_str)
         if cached_result is not None:
-            result = (
-                str(cached_result)
-                if not isinstance(cached_result, str)
-                else cached_result
-            )
+            raw_tool_result = cached_result
+            result = format_native_tool_output_for_agent(output_tool, cached_result)
             from_cache = True
 
     started_at = datetime.now()
@@ -1486,12 +1505,6 @@ def execute_single_native_tool_call(
 
     track_delegation_if_needed(func_name, args_dict, task)
 
-    structured_tool: CrewStructuredTool | None = None
-    for structured in structured_tools or []:
-        if sanitize_tool_name(structured.name) == func_name:
-            structured_tool = structured
-            break
-
     hook_blocked = False
     before_hook_context = ToolCallHookContext(
         tool_name=func_name,
@@ -1512,11 +1525,13 @@ def execute_single_native_tool_call(
     error_event_emitted = False
     if hook_blocked:
         result = f"Tool execution blocked by hook. Tool: {func_name}"
+        raw_tool_result = result
     elif not from_cache:
-        if func_name in available_functions:
+        if func_name in available_functions and output_tool is not None:
             try:
                 tool_func = available_functions[func_name]
                 raw_result = tool_func(**args_dict)
+                raw_tool_result = raw_result
 
                 if tools_handler and tools_handler.cache:
                     should_cache = True
@@ -1529,11 +1544,10 @@ def execute_single_native_tool_call(
                             tool=func_name, input=input_str, output=raw_result
                         )
 
-                result = (
-                    str(raw_result) if not isinstance(raw_result, str) else raw_result
-                )
+                result = format_native_tool_output_for_agent(output_tool, raw_result)
             except Exception as e:
                 result = f"Error executing tool: {e}"
+                raw_tool_result = result
                 if task:
                     task.increment_tools_errors()
                 crewai_event_bus.emit(
@@ -1559,6 +1573,7 @@ def execute_single_native_tool_call(
         task=task,
         crew=crew,
         tool_result=result,
+        raw_tool_result=raw_tool_result,
     )
     try:
         for after_hook in get_after_tool_call_hooks():

lib/crewai/src/crewai/utilities/declarative_refs.py

@@ -0,0 +1,69 @@
+"""Resolve Python refs used in project definitions.
+
+A ref must use this form: ``module:qualname``. ``module`` must name a Python
+module we can import. ``qualname`` must name something inside that module. For
+example, ``crewai_tools:SerperDevTool`` imports ``crewai_tools`` and returns
+``SerperDevTool`` from it. Dots in ``qualname`` mean nested attributes.
+
+Examples:
+
+- ``crewai_tools:SerperDevTool`` imports ``crewai_tools`` and returns
+  ``SerperDevTool``.
+- ``my_app.tools:Factory.build`` imports ``my_app.tools``, gets ``Factory``,
+  then gets ``build`` from ``Factory``.
+- ``crewai_tools`` is invalid because it has no ``:``.
+- ``crewai_tools:`` is invalid because it has no ``qualname``.
+
+These helpers are the shared contract for YAML/JSON definitions:
+
+- ``resolve_ref()`` checks the ref, imports the module, and returns the symbol
+  as-is.
+- ``resolve_class_ref()`` does the same work, then checks that the symbol is a
+  class. It can also check that the class extends a base class. It does not
+  create an object.
+
+These helpers import user code. Code that must avoid that should check the raw
+string shape instead.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from operator import attrgetter
+from typing import Any
+
+
+class InvalidRefError(ValueError):
+    """A definition ref that cannot be resolved to a live Python symbol."""
+
+
+def resolve_ref(ref: str, *, field: str) -> Any:
+    """Return the Python symbol named by a project definition field."""
+    module_name, _, qualname = ref.partition(":")
+    if "<" in ref or not module_name or not qualname:
+        raise InvalidRefError(
+            f"invalid {field} ref {ref!r}; expected 'module:qualname'"
+        )
+    try:
+        return attrgetter(qualname)(importlib.import_module(module_name))
+    except (ImportError, AttributeError) as e:
+        raise InvalidRefError(f"unresolvable {field} ref {ref!r}") from e
+
+
+def resolve_class_ref(
+    ref: str,
+    *,
+    field: str,
+    base_class: type[Any] | None = None,
+) -> type[Any]:
+    """Return the named class, with an optional base class check."""
+    target = resolve_ref(ref, field=field)
+    if not inspect.isclass(target):
+        raise InvalidRefError(f"invalid {field} ref {ref!r}; expected a class")
+    if base_class is not None and not issubclass(target, base_class):
+        raise InvalidRefError(
+            f"invalid {field} ref {ref!r}; expected a subclass of "
+            f"{base_class.__module__}.{base_class.__name__}"
+        )
+    return target

lib/crewai/src/crewai/utilities/tool_utils.py

@@ -116,6 +116,7 @@ async def aexecute_tool_and_check_finality(
             logger.log("error", f"Error in before_tool_call hook: {e}")
 
         tool_result = await tool_usage.ause(tool_calling, agent_action.text)
+        raw_tool_result = tool_usage.get_last_raw_result(tool_result)
 
         after_hook_context = ToolCallHookContext(
             tool_name=sanitized_tool_name,
@@ -125,6 +126,7 @@ async def aexecute_tool_and_check_finality(
             task=task,
             crew=crew,
             tool_result=tool_result,
+            raw_tool_result=raw_tool_result,
         )
 
         after_hooks = get_after_tool_call_hooks()
@@ -234,6 +236,7 @@ def execute_tool_and_check_finality(
             logger.log("error", f"Error in before_tool_call hook: {e}")
 
         tool_result = tool_usage.use(tool_calling, agent_action.text)
+        raw_tool_result = tool_usage.get_last_raw_result(tool_result)
 
         after_hook_context = ToolCallHookContext(
             tool_name=sanitized_tool_name,
@@ -243,6 +246,7 @@ def execute_tool_and_check_finality(
             task=task,
             crew=crew,
             tool_result=tool_result,
+            raw_tool_result=raw_tool_result,
         )
 
         after_hooks = get_after_tool_call_hooks()

lib/crewai/tests/agents/test_agent_executor.py

@@ -7,6 +7,7 @@ flow methods, routing logic, and error handling.
 from __future__ import annotations
 
 import asyncio
+import threading
 from types import SimpleNamespace
 import time
 from typing import Any
@@ -39,8 +40,6 @@ def _build_executor(**kwargs: Any) -> AgentExecutor:
     executor._human_feedback_method_outputs = {}
     executor._input_history = []
     executor._is_execution_resuming = False
-    import threading
-    executor._state_lock = threading.Lock()
     executor._or_listeners_lock = threading.Lock()
     executor._execution_lock = threading.Lock()
     executor._finalize_lock = threading.Lock()

lib/crewai/tests/agents/test_native_tool_calling.py

@@ -7,6 +7,7 @@ when the LLM supports it, across multiple providers.
 from __future__ import annotations
 
 from collections.abc import Generator
+import json
 import os
 import threading
 import time
@@ -20,7 +21,7 @@ from crewai import Agent, Crew, Task
 from crewai.agents.parser import AgentFinish
 from crewai.events import crewai_event_bus
 from crewai.hooks import register_after_tool_call_hook, register_before_tool_call_hook
-from crewai.hooks.tool_hooks import ToolCallHookContext
+from crewai.hooks.tool_hooks import ToolCallHookContext, clear_after_tool_call_hooks
 from crewai.llm import LLM
 from crewai.tools.base_tool import BaseTool
 
@@ -1197,6 +1198,76 @@ class TestNativeToolCallingJsonParseError:
 
         assert result["result"] == "ran: print(1)"
 
+    def test_typed_output_is_json_agent_text(self) -> None:
+        class SearchOutput(BaseModel):
+            query: str
+            score: float
+
+        class TypedSearchTool(BaseTool):
+            name: str = "typed_search"
+            description: str = "Search for information"
+            result_schema: type[BaseModel] = SearchOutput
+
+            def _run(self, query: str) -> SearchOutput:
+                return SearchOutput(query=query, score=0.8)
+
+        tool = TypedSearchTool()
+        executor = self._make_executor([tool])
+
+        from crewai.utilities.agent_utils import convert_tools_to_openai_schema
+
+        _, available_functions, _ = convert_tools_to_openai_schema([tool])
+
+        result = executor._execute_single_native_tool_call(
+            call_id="call_typed",
+            func_name="typed_search",
+            func_args='{"query": "crew"}',
+            available_functions=available_functions,
+        )
+
+        assert json.loads(result["result"]) == {"query": "crew", "score": 0.8}
+
+    def test_typed_output_after_hook_includes_raw_tool_result(self) -> None:
+        from crewai.utilities.agent_utils import convert_tools_to_openai_schema
+
+        class SearchOutput(BaseModel):
+            query: str
+            score: float
+
+        class TypedSearchTool(BaseTool):
+            name: str = "typed_search"
+            description: str = "Search for information"
+            result_schema: type[BaseModel] = SearchOutput
+
+            def _run(self, query: str) -> SearchOutput:
+                return SearchOutput(query=query, score=0.8)
+
+        seen_results: list[tuple[str | None, object]] = []
+
+        def after_hook(context: ToolCallHookContext) -> None:
+            seen_results.append((context.tool_result, context.raw_tool_result))
+
+        tool = TypedSearchTool()
+        executor = self._make_executor([tool])
+        _, available_functions, _ = convert_tools_to_openai_schema([tool])
+
+        clear_after_tool_call_hooks()
+        register_after_tool_call_hook(after_hook)
+        try:
+            result = executor._execute_single_native_tool_call(
+                call_id="call_typed",
+                func_name="typed_search",
+                func_args='{"query": "crew"}',
+                available_functions=available_functions,
+            )
+        finally:
+            clear_after_tool_call_hooks()
+
+        assert json.loads(result["result"]) == {"query": "crew", "score": 0.8}
+        assert seen_results == [
+            ('{"query":"crew","score":0.8}', SearchOutput(query="crew", score=0.8))
+        ]
+
     def test_native_tool_loop_falls_back_when_provider_rejects_tools(self) -> None:
         """Unsupported native tools errors should continue through ReAct."""
 

lib/crewai/tests/cli/test_run_crew.py

@@ -11,11 +11,10 @@ import pytest
 
 from crewai_cli.cli import run
 from crewai_cli.run_crew import (
-    CrewType,
+    _execute_uv_script,
     _load_json_crew_for_tui,
     _missing_input_names,
     _prompt_for_missing_inputs,
-    execute_command,
 )
 
 
@@ -30,6 +29,8 @@ def test_run_passes_filename_to_run_crew(run_crew_mock: mock.Mock, runner: CliRu
 
     run_crew_mock.assert_called_once_with(
         trained_agents_file="my_custom_trained.pkl",
+        definition=None,
+        inputs=None,
     )
     assert result.exit_code == 0
 
@@ -38,7 +39,11 @@ def test_run_passes_filename_to_run_crew(run_crew_mock: mock.Mock, runner: CliRu
 def test_run_without_filename_passes_none(run_crew_mock: mock.Mock, runner: CliRunner) -> None:
     result = runner.invoke(run)
 
-    run_crew_mock.assert_called_once_with(trained_agents_file=None)
+    run_crew_mock.assert_called_once_with(
+        trained_agents_file=None,
+        definition=None,
+        inputs=None,
+    )
     assert result.exit_code == 0
 
 
@@ -50,7 +55,11 @@ def test_run_without_filename_passes_none(run_crew_mock: mock.Mock, runner: CliR
 def test_execute_command_sets_env_var_when_filename_provided(
     _build_env: mock.Mock, subprocess_run: mock.Mock
 ) -> None:
-    execute_command(CrewType.STANDARD, trained_agents_file="my_custom_trained.pkl")
+    _execute_uv_script(
+        "run_crew",
+        entity_type="crew",
+        trained_agents_file="my_custom_trained.pkl",
+    )
 
     _, kwargs = subprocess_run.call_args
     assert kwargs["env"]["CREWAI_TRAINED_AGENTS_FILE"] == "my_custom_trained.pkl"
@@ -65,7 +74,7 @@ def test_execute_command_sets_env_var_when_filename_provided(
 def test_execute_command_omits_env_var_when_filename_absent(
     _build_env: mock.Mock, subprocess_run: mock.Mock
 ) -> None:
-    execute_command(CrewType.STANDARD)
+    _execute_uv_script("run_crew", entity_type="crew")
 
     _, kwargs = subprocess_run.call_args
     assert "CREWAI_TRAINED_AGENTS_FILE" not in kwargs["env"]

lib/crewai/tests/experimental/skills/test_cache.py

@@ -8,7 +8,9 @@ import json
 import tarfile
 from pathlib import Path
 
-from crewai.experimental.skills.cache import SkillCacheManager
+import pytest
+
+from crewai.experimental.skills.cache import SkillCacheManager, _safe_extractall
 
 
 def _make_tar_gz(files: dict[str, str]) -> bytes:
@@ -35,6 +37,15 @@ def _make_tar_gz(files: dict[str, str]) -> bytes:
     return out.getvalue()
 
 
+def _tar_from_members(build) -> tarfile.TarFile:
+    """Build an in-memory tar archive via `build(tf)` and return it for reading."""
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w") as tf:
+        build(tf)
+    buf.seek(0)
+    return tarfile.open(fileobj=buf, mode="r")
+
+
 class TestSkillCacheManager:
     def test_get_cached_path_missing(self, tmp_path: Path) -> None:
         cache = SkillCacheManager(cache_root=tmp_path)
@@ -113,3 +124,85 @@ class TestSkillCacheManager:
         dest = cache.store("acme", "my-skill", None, archive)
         meta = json.loads((dest / ".crewai_meta.json").read_text())
         assert meta["version"] is None
+
+
+def test_safe_extractall_blocks_symlink_escaping_cache_destination(
+    tmp_path: Path,
+) -> None:
+    """A symlink whose target escapes dest is rejected before extraction."""
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    dest = tmp_path / "dest"
+    dest.mkdir()
+
+    def build(tf: tarfile.TarFile) -> None:
+        link = tarfile.TarInfo("link")
+        link.type = tarfile.SYMTYPE
+        link.linkname = str(outside)
+        tf.addfile(link)
+        payload = b"pwned"
+        info = tarfile.TarInfo("link/evil.txt")
+        info.size = len(payload)
+        tf.addfile(info, io.BytesIO(payload))
+
+    with _tar_from_members(build) as tf:
+        with pytest.raises(ValueError, match="escaping destination"):
+            _safe_extractall(tf, dest)
+
+    assert not (outside / "evil.txt").exists()
+
+
+def test_safe_extractall_blocks_hardlink_escaping_cache_destination(
+    tmp_path: Path,
+) -> None:
+    """A hardlink whose target escapes dest is rejected."""
+    dest = tmp_path / "dest"
+    dest.mkdir()
+
+    def build(tf: tarfile.TarFile) -> None:
+        link = tarfile.TarInfo("escape")
+        link.type = tarfile.LNKTYPE
+        link.linkname = "../outside.txt"
+        tf.addfile(link)
+
+    with _tar_from_members(build) as tf:
+        with pytest.raises(ValueError, match="escaping destination"):
+            _safe_extractall(tf, dest)
+
+
+def test_safe_extractall_blocks_special_cache_tar_member(tmp_path: Path) -> None:
+    """Special tar members such as FIFOs are rejected."""
+    dest = tmp_path / "dest"
+    dest.mkdir()
+
+    def build(tf: tarfile.TarFile) -> None:
+        fifo = tarfile.TarInfo("pipe")
+        fifo.type = tarfile.FIFOTYPE
+        tf.addfile(fifo)
+
+    with _tar_from_members(build) as tf:
+        with pytest.raises(ValueError, match="unsupported tar member"):
+            _safe_extractall(tf, dest)
+
+
+def test_safe_extractall_allows_benign_cache_symlink(tmp_path: Path) -> None:
+    """A symlink that stays within dest is permitted."""
+    dest = tmp_path / "dest"
+    dest.mkdir()
+
+    def build(tf: tarfile.TarFile) -> None:
+        payload = b"hi"
+        info = tarfile.TarInfo("real.txt")
+        info.size = len(payload)
+        tf.addfile(info, io.BytesIO(payload))
+        link = tarfile.TarInfo("alias.txt")
+        link.type = tarfile.SYMTYPE
+        link.linkname = "real.txt"
+        tf.addfile(link)
+
+    with _tar_from_members(build) as tf:
+        _safe_extractall(tf, dest)
+
+    assert (dest / "real.txt").read_bytes() == b"hi"
+    assert (dest / "alias.txt").is_symlink()
+    assert (dest / "alias.txt").readlink() == Path("real.txt")

lib/crewai/tests/hooks/test_tool_hooks.py

@@ -91,20 +91,24 @@ class TestToolCallHookContext:
         assert context.task == mock_task
         assert context.crew == mock_crew
         assert context.tool_result is None
+        assert context.raw_tool_result is None
 
     def test_context_with_result(self, mock_tool):
         """Test that context includes result when provided."""
         tool_input = {"arg1": "value1"}
         tool_result = "Test tool result"
+        raw_tool_result = {"value": 42}
 
         context = ToolCallHookContext(
             tool_name="test_tool",
             tool_input=tool_input,
             tool=mock_tool,
             tool_result=tool_result,
+            raw_tool_result=raw_tool_result,
         )
 
         assert context.tool_result == tool_result
+        assert context.raw_tool_result == raw_tool_result
 
     def test_tool_input_is_mutable_reference(self, mock_tool):
         """Test that modifying context.tool_input modifies the original dict."""

lib/crewai/tests/project/test_json_loader.py

@@ -385,12 +385,52 @@ class TestLoadAgentFromDefinition:
 
 
 class TestResolveTools:
+    def test_import_ref_tool_resolves(self, tmp_path, monkeypatch):
+        from crewai.project.json_loader import _resolve_tools
+
+        (tmp_path / "project_tools.py").write_text(
+            "from crewai.tools.base_tool import BaseTool\n"
+            "\n"
+            "class LookupTool(BaseTool):\n"
+            "    name: str = 'lookup'\n"
+            "    description: str = 'lookup input'\n"
+            "\n"
+            "    def _run(self, text: str) -> str:\n"
+            "        return text\n"
+        )
+        monkeypatch.syspath_prepend(str(tmp_path))
+
+        tools = _resolve_tools(["project_tools:LookupTool"])
+
+        assert len(tools) == 1
+        assert tools[0].name == "lookup"
+
     def test_unknown_tool_raises_with_guidance(self):
         from crewai.project.json_loader import JSONProjectError, _resolve_tools
 
         with pytest.raises(JSONProjectError, match="Unknown tool 'NotARealToolXYZ'"):
             _resolve_tools(["NotARealToolXYZ"])
 
+    def test_import_ref_tool_must_resolve_to_basetool_class(
+        self, tmp_path, monkeypatch
+    ):
+        from crewai.project.json_loader import JSONProjectError, _resolve_tools
+
+        (tmp_path / "not_tools.py").write_text(
+            "class NotATool:\n"
+            "    pass\n"
+        )
+        monkeypatch.syspath_prepend(str(tmp_path))
+
+        with pytest.raises(JSONProjectError, match="expected a BaseTool class"):
+            _resolve_tools(["not_tools:NotATool"])
+
+    def test_unresolvable_import_ref_tool_raises_guidance(self):
+        from crewai.project.json_loader import JSONProjectError, _resolve_tools
+
+        with pytest.raises(JSONProjectError, match="unresolvable tool ref"):
+            _resolve_tools(["not_a_real_module:MissingTool"])
+
     def test_missing_custom_tool_raises(self, tmp_path, monkeypatch):
         from crewai.project.json_loader import JSONProjectError, _resolve_tools
 
@@ -505,6 +545,30 @@ class TestValidationDoesNotExecuteTools:
 
         assert not sentinel.exists(), "validation must not import Python refs"
 
+    def test_validate_does_not_import_tool_refs(
+        self, tmp_path, monkeypatch: pytest.MonkeyPatch
+    ):
+        from crewai.project.json_loader import validate_crew_project
+
+        sentinel = tmp_path / "tool_ref_executed.txt"
+        (tmp_path / "project_tools.py").write_text(
+            "from pathlib import Path\n"
+            f"Path({str(sentinel)!r}).write_text('boom')\n"
+            "from crewai.tools.base_tool import BaseTool\n"
+            "class LookupTool(BaseTool):\n"
+            "    name: str = 'lookup'\n"
+            "    description: str = 'lookup input'\n"
+            "    def _run(self, text: str) -> str:\n"
+            "        return text\n"
+        )
+        monkeypatch.syspath_prepend(str(tmp_path))
+        sys.modules.pop("project_tools", None)
+        crew_path = self._write_project(tmp_path, tool_line='"project_tools:LookupTool"')
+
+        validate_crew_project(crew_path, tmp_path / "agents")
+
+        assert not sentinel.exists(), "validation must not import tool refs"
+
     def test_validate_reports_missing_custom_tool_file(self, tmp_path):
         from crewai.project.json_loader import (
             JSONProjectValidationError,

lib/crewai/tests/test_flow.py

@@ -386,6 +386,54 @@ def test_router_runtime_uses_flow_definition_without_legacy_router_metadata():
     assert execution_order == ["begin", "decide", "handle_left"]
 
 
+def test_start_router_runtime_routes_public_dsl_return_value():
+    execution_order = []
+
+    class StartRouterFlow(Flow):
+        @start()
+        @router(emit=["continue"])
+        def decide(self):
+            execution_order.append("decide")
+            return "continue"
+
+        @listen("continue")
+        def handle_continue(self, result):
+            execution_order.append(f"handle_continue:{result}")
+            return "done"
+
+    assert StartRouterFlow().kickoff() == "done"
+    assert execution_order == ["decide", "handle_continue:continue"]
+
+
+def test_start_router_runtime_chains_to_stacked_listener_router():
+    execution_order = []
+
+    class ChainedStartRouterFlow(Flow):
+        @start()
+        @router(emit=["approved", "not_approved"])
+        def first_router(self):
+            execution_order.append("first_router")
+            return "approved"
+
+        @listen("approved")
+        @router(emit=["second_approval", "not_approved"])
+        def second_router(self):
+            execution_order.append("second_router")
+            return "second_approval"
+
+        @listen("second_approval")
+        def handle_second_approval(self, result):
+            execution_order.append(f"handle_second_approval:{result}")
+            return "done"
+
+    assert ChainedStartRouterFlow().kickoff() == "done"
+    assert execution_order == [
+        "first_router",
+        "second_router",
+        "handle_second_approval:second_approval",
+    ]
+
+
 def test_router_falsy_result_emits_runtime_event():
     execution_order = []
 
@@ -1462,42 +1510,36 @@ def test_conditional_router_events_exclusivity():
     assert "handle_event_c" not in execution_order
 
 
-def test_state_consistency_across_parallel_branches():
-    """Test that state remains consistent when branches execute in parallel.
+def test_and_join_waits_for_parallel_branches():
+    """Test that sibling branches complete before a joined listener runs.
 
-    Note: Branches triggered by the same parent execute in parallel for efficiency.
-    Thread-safe state access via StateProxy ensures no race conditions.
-    We check the execution order to ensure the branches execute in parallel.
+    Branches triggered by the same parent execute in parallel for efficiency.
+    Shared state updates are not guaranteed to be atomic, so this test uses a
+    locked local recorder instead of branch state mutation.
     """
     execution_order = []
+    execution_order_lock = threading.Lock()
+
+    def record(method_name: str) -> None:
+        with execution_order_lock:
+            execution_order.append(method_name)
 
     class StateConsistencyFlow(Flow):
-        def __init__(self):
-            super().__init__()
-            self.state["counter"] = 0
-            self.state["branch_a_value"] = None
-            self.state["branch_b_value"] = None
-
         @start()
         def init(self):
-            execution_order.append("init")
-            self.state["counter"] = 10
+            record("init")
 
         @listen(init)
         def branch_a(self):
-            execution_order.append("branch_a")
-            self.state["branch_a_value"] = self.state["counter"]
-            self.state["counter"] += 1
+            record("branch_a")
 
         @listen(init)
         def branch_b(self):
-            execution_order.append("branch_b")
-            self.state["branch_b_value"] = self.state["counter"]
-            self.state["counter"] += 5
+            record("branch_b")
 
         @listen(and_(branch_a, branch_b))
         def verify_state(self):
-            execution_order.append("verify_state")
+            record("verify_state")
 
     flow = StateConsistencyFlow()
     flow.kickoff()
@@ -1506,10 +1548,8 @@ def test_state_consistency_across_parallel_branches():
     assert "branch_b" in execution_order
     assert "verify_state" in execution_order
 
-    assert flow.state["branch_a_value"] is not None
-    assert flow.state["branch_b_value"] is not None
-
-    assert flow.state["counter"] == 16
+    assert execution_order.index("branch_a") < execution_order.index("verify_state")
+    assert execution_order.index("branch_b") < execution_order.index("verify_state")
 
 
 def test_deeply_nested_conditions():