Merge branch 'main' into fix/file-tools-path-allowlist

Restrict docs broken-links workflow permissions (#6330 )
docs: snapshot and changelog for v1.14.8a5 (#6329 )
2026-06-26 10:38:10 +00:00 · 2026-06-25 12:02:07 +08:00 · 2026-06-25 10:52:33 +08:00 · 2026-06-24 17:31:32 -07:00 · 2026-06-24 17:25:08 -07:00 · 2026-06-24 16:37:51 -07:00
45 changed files with 727 additions and 519 deletions
--- a/.github/workflows/docs-broken-links.yml
+++ b/.github/workflows/docs-broken-links.yml
@@ -13,6 +13,9 @@ on:
      - "docs.json"
  workflow_dispatch:

+permissions:
+  contents: read
+
 jobs:
  check-links:
    name: Check broken links
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -397,8 +397,14 @@
                    "group": "Build",
                    "pages": [
                      "edge/en/enterprise/features/automations",
-                      "edge/en/enterprise/features/crew-studio",
-                      "edge/en/enterprise/features/merged-step-card",
+                      {
+                        "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",
@@ -922,8 +928,14 @@
                    "group": "Build",
                    "pages": [
                      "v1.14.7/en/enterprise/features/automations",
-                      "v1.14.7/en/enterprise/features/crew-studio",
-                      "v1.14.7/en/enterprise/features/merged-step-card",
+                      {
+                        "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",
@@ -8549,8 +8561,14 @@
                    "group": "Construir",
                    "pages": [
                      "edge/pt-BR/enterprise/features/automations",
-                      "edge/pt-BR/enterprise/features/crew-studio",
-                      "edge/pt-BR/enterprise/features/merged-step-card",
+                      {
+                        "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",
@@ -9051,8 +9069,14 @@
                    "group": "Construir",
                    "pages": [
                      "v1.14.7/pt-BR/enterprise/features/automations",
-                      "v1.14.7/pt-BR/enterprise/features/crew-studio",
-                      "v1.14.7/pt-BR/enterprise/features/merged-step-card",
+                      {
+                        "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",
@@ -16415,8 +16439,14 @@
                    "group": "빌드",
                    "pages": [
                      "edge/ko/enterprise/features/automations",
-                      "edge/ko/enterprise/features/crew-studio",
-                      "edge/ko/enterprise/features/merged-step-card",
+                      {
+                        "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",
@@ -16929,8 +16959,14 @@
                    "group": "빌드",
                    "pages": [
                      "v1.14.7/ko/enterprise/features/automations",
-                      "v1.14.7/ko/enterprise/features/crew-studio",
-                      "v1.14.7/ko/enterprise/features/merged-step-card",
+                      {
+                        "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",
@@ -24473,8 +24509,14 @@
                    "group": "البناء",
                    "pages": [
                      "edge/ar/enterprise/features/automations",
-                      "edge/ar/enterprise/features/crew-studio",
-                      "edge/ar/enterprise/features/merged-step-card",
+                      {
+                        "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",
@@ -24987,8 +25029,14 @@
                    "group": "البناء",
                    "pages": [
                      "v1.14.7/ar/enterprise/features/automations",
-                      "v1.14.7/ar/enterprise/features/crew-studio",
-                      "v1.14.7/ar/enterprise/features/merged-step-card",
+                      {
+                        "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",
--- a/docs/edge/ar/changelog.mdx
+++ b/docs/edge/ar/changelog.mdx
@@ -4,6 +4,32 @@ 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

--- a/docs/edge/ar/enterprise/features/merged-step-card.mdx
+++ b/docs/edge/ar/enterprise/features/merged-step-card.mdx
@@ -5,11 +5,6 @@ icon: "layer-group"
 mode: "wide"
 ---

-{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
-<Note>
-  **الإطلاق يوم الأربعاء 24 يونيو.** تنتقل لوحة Studio إلى بطاقة واحدة لكل خطوة بدلاً من عُقد منفصلة للمهمة والوكيل، وذلك لتبسيط اللوحة مع إضافتنا لوظائف جديدة قريبًا. تستمر أتمتتك الحالية في العمل دون أي تغييرات مطلوبة — تبقى جميع إعدادات المهمة والوكيل متاحة، ولكن منظّمة في بطاقة واحدة.
-</Note>
-
 ## نظرة عامة

 على لوحة Studio، تُمثَّل كل خطوة عمل بـ **بطاقة واحدة**. تجمع البطاقة بين عنصرين كانا في السابق في عُقد منفصلة:
--- a/docs/edge/en/changelog.mdx
+++ b/docs/edge/en/changelog.mdx
@@ -4,6 +4,32 @@ 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

--- a/docs/edge/en/enterprise/features/merged-step-card.mdx
+++ b/docs/edge/en/enterprise/features/merged-step-card.mdx
@@ -5,11 +5,6 @@ icon: "layer-group"
 mode: "wide"
 ---

-{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
-<Note>
-  **Rolling out Wednesday, June 24th.** The Studio canvas is moving to one card per step instead of separate task and agent nodes, to streamline the canvas as we add new functionality soon. Your existing automations keep working with no changes needed — every task and agent setting is still available, just organized onto a single card.
-</Note>
-
 ## 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:
--- a/docs/edge/en/tools/file-document/filewritetool.mdx
+++ b/docs/edge/en/tools/file-document/filewritetool.mdx
@@ -42,6 +42,25 @@ print(result)
 - `content`: The content to write into the file.
 - `directory` (optional): The path to the directory where the file will be created. Defaults to the current directory (`.`). If the directory does not exist, it will be created.

+## Path confinement
+
+Because `filename` and `directory` may be supplied at runtime by an agent acting on untrusted content, `FileWriterTool` confines writes to an **allow-listed set of root directories**. The resolved target (after expanding symlinks and `..`) must fall inside one of these roots or the write is rejected — a `directory` argument pointing outside them (e.g. `~/.ssh`, `/etc`) no longer grants write access.
+
+The allow-list is, by default, the current working directory. You can extend it for deployments that legitimately write elsewhere:
+
+- `CREWAI_TOOLS_ALLOWED_DIRS` — one or more additional root directories, separated by the OS path separator (`:` on Linux/macOS, `;` on Windows).
+
+```shell
+# Allow writes under /data and /workspace in addition to the cwd
+export CREWAI_TOOLS_ALLOWED_DIRS="/data:/workspace"
+```
+
+<Warning>
+  If the process runs with its working directory set to the filesystem root (`/`) — common in containers started without a `WORKDIR` — the tool will **not** fall back to allow-listing the entire filesystem. Writes fail with a `ValueError` until you set `CREWAI_TOOLS_ALLOWED_DIRS` to an explicit directory. Set a `WORKDIR` (or the env var) in such deployments.
+</Warning>
+
+The `CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true` escape hatch disables path validation entirely. It is intended only for trusted local development and should not be set in any environment that runs agent-generated or otherwise untrusted instructions.
+
 ## Conclusion

 By integrating the `FileWriterTool` into your crews, the agents can reliably write content to files across different operating systems. 
--- a/docs/edge/ko/changelog.mdx
+++ b/docs/edge/ko/changelog.mdx
@@ -4,6 +4,32 @@ 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

--- a/docs/edge/ko/enterprise/features/merged-step-card.mdx
+++ b/docs/edge/ko/enterprise/features/merged-step-card.mdx
@@ -5,11 +5,6 @@ icon: "layer-group"
 mode: "wide"
 ---

-{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
-<Note>
-  **6월 24일 수요일 출시.** Studio 캔버스가 작업과 에이전트를 별도의 노드로 표시하는 대신 단계당 하나의 카드로 전환됩니다. 곧 추가될 새로운 기능을 위해 캔버스를 간소화하기 위한 변경입니다. 기존 자동화는 아무런 변경 없이 그대로 동작하며, 모든 작업 및 에이전트 설정은 단일 카드에 정리되어 그대로 사용할 수 있습니다.
-</Note>
-
 ## 개요

 Studio 캔버스에서 각 작업 단계는 **하나의 카드**로 표현됩니다. 이 카드는 이전에 별도의 노드에 있던 두 가지를 결합합니다:
--- a/docs/edge/pt-BR/changelog.mdx
+++ b/docs/edge/pt-BR/changelog.mdx
@@ -4,6 +4,32 @@ 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

--- a/docs/edge/pt-BR/enterprise/features/merged-step-card.mdx
+++ b/docs/edge/pt-BR/enterprise/features/merged-step-card.mdx
@@ -5,11 +5,6 @@ icon: "layer-group"
 mode: "wide"
 ---

-{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
-<Note>
-  **Lançamento na quarta-feira, 24 de junho.** O canvas do Studio passa a exibir um card por etapa, em vez de nós separados para tarefa e agente, para simplificar o canvas à medida que adicionamos novas funcionalidades em breve. Suas automações existentes continuam funcionando sem nenhuma alteração necessária — cada configuração de tarefa e de agente continua disponível, apenas organizada em um único card.
-</Note>
-
 ## 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/docs/v1.14.7/ar/enterprise/features/merged-step-card.mdx
+++ b/docs/v1.14.7/ar/enterprise/features/merged-step-card.mdx
@@ -5,11 +5,6 @@ icon: "layer-group"
 mode: "wide"
 ---

-{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
-<Note>
-  **الإطلاق يوم الأربعاء 24 يونيو.** تنتقل لوحة Studio إلى بطاقة واحدة لكل خطوة بدلاً من عُقد منفصلة للمهمة والوكيل، وذلك لتبسيط اللوحة مع إضافتنا لوظائف جديدة قريبًا. تستمر أتمتتك الحالية في العمل دون أي تغييرات مطلوبة — تبقى جميع إعدادات المهمة والوكيل متاحة، ولكن منظّمة في بطاقة واحدة.
-</Note>
-
 ## نظرة عامة

 على لوحة Studio، تُمثَّل كل خطوة عمل بـ **بطاقة واحدة**. تجمع البطاقة بين عنصرين كانا في السابق في عُقد منفصلة:
--- a/docs/v1.14.7/en/enterprise/features/merged-step-card.mdx
+++ b/docs/v1.14.7/en/enterprise/features/merged-step-card.mdx
@@ -5,11 +5,6 @@ icon: "layer-group"
 mode: "wide"
 ---

-{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
-<Note>
-  **Rolling out Wednesday, June 24th.** The Studio canvas is moving to one card per step instead of separate task and agent nodes, to streamline the canvas as we add new functionality soon. Your existing automations keep working with no changes needed — every task and agent setting is still available, just organized onto a single card.
-</Note>
-
 ## 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:
--- a/docs/v1.14.7/ko/enterprise/features/merged-step-card.mdx
+++ b/docs/v1.14.7/ko/enterprise/features/merged-step-card.mdx
@@ -5,11 +5,6 @@ icon: "layer-group"
 mode: "wide"
 ---

-{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
-<Note>
-  **6월 24일 수요일 출시.** Studio 캔버스가 작업과 에이전트를 별도의 노드로 표시하는 대신 단계당 하나의 카드로 전환됩니다. 곧 추가될 새로운 기능을 위해 캔버스를 간소화하기 위한 변경입니다. 기존 자동화는 아무런 변경 없이 그대로 동작하며, 모든 작업 및 에이전트 설정은 단일 카드에 정리되어 그대로 사용할 수 있습니다.
-</Note>
-
 ## 개요

 Studio 캔버스에서 각 작업 단계는 **하나의 카드**로 표현됩니다. 이 카드는 이전에 별도의 노드에 있던 두 가지를 결합합니다:
--- a/docs/v1.14.7/pt-BR/enterprise/features/merged-step-card.mdx
+++ b/docs/v1.14.7/pt-BR/enterprise/features/merged-step-card.mdx
@@ -5,11 +5,6 @@ icon: "layer-group"
 mode: "wide"
 ---

-{/* CLEANUP: This <Note> banner is the only time-bound content on the page. After the feature ships (Wednesday, June 24th 2026), delete the banner below — the rest of the page is evergreen present-tense docs and needs no other edits. */}
-<Note>
-  **Lançamento na quarta-feira, 24 de junho.** O canvas do Studio passa a exibir um card por etapa, em vez de nós separados para tarefa e agente, para simplificar o canvas à medida que adicionamos novas funcionalidades em breve. Suas automações existentes continuam funcionando sem nenhuma alteração necessária — cada configuração de tarefa e de agente continua disponível, apenas organizada em um único card.
-</Note>
-
 ## 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/lib/cli/pyproject.toml
+++ b/lib/cli/pyproject.toml
@@ -8,7 +8,7 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "crewai-core==1.14.8a4",
+    "crewai-core==1.14.8a5",
    "click>=8.1.7,<9",
    "pydantic>=2.11.9,<2.13",
    "pydantic-settings~=2.10.1",
--- a/lib/cli/src/crewai_cli/init.py
+++ b/lib/cli/src/crewai_cli/init.py
@@ -1 +1 @@
-__version__ = "1.14.8a4"
+__version__ = "1.14.8a5"
--- a/lib/cli/src/crewai_cli/templates/crew/pyproject.toml
+++ b/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.8a4"
+    "crewai[tools]==1.14.8a5"
 ]

 [project.scripts]
--- a/lib/cli/src/crewai_cli/templates/declarative_flow/pyproject.toml
+++ b/lib/cli/src/crewai_cli/templates/declarative_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.8a4"
+    "crewai[tools]==1.14.8a5"
 ]

 [build-system]
--- a/lib/cli/src/crewai_cli/templates/flow/pyproject.toml
+++ b/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.8a4"
+    "crewai[tools]==1.14.8a5"
 ]

 [project.scripts]
--- a/lib/cli/src/crewai_cli/templates/tool/pyproject.toml
+++ b/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.8a4"
+    "crewai[tools]==1.14.8a5"
 ]

 [tool.crewai]
--- a/lib/crewai-core/src/crewai_core/init.py
+++ b/lib/crewai-core/src/crewai_core/init.py
@@ -1 +1 @@
-__version__ = "1.14.8a4"
+__version__ = "1.14.8a5"
--- a/lib/crewai-files/src/crewai_files/init.py
+++ b/lib/crewai-files/src/crewai_files/init.py
@@ -152,4 +152,4 @@ __all__ = [
    "wrap_file_source",
 ]

-__version__ = "1.14.8a4"
+__version__ = "1.14.8a5"
--- a/lib/crewai-tools/pyproject.toml
+++ b/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.8a4",
+    "crewai==1.14.8a5",
    "tiktoken>=0.8.0,<0.13",
    "beautifulsoup4~=4.13.4",
    "python-docx~=1.2.0",
--- a/lib/crewai-tools/src/crewai_tools/init.py
+++ b/lib/crewai-tools/src/crewai_tools/init.py
@@ -330,4 +330,4 @@ __all__ = [
    "ZapierActionTools",
 ]

-__version__ = "1.14.8a4"
+__version__ = "1.14.8a5"
--- a/lib/crewai-tools/src/crewai_tools/security/safe_path.py
+++ b/lib/crewai-tools/src/crewai_tools/security/safe_path.py
@@ -20,6 +20,82 @@ from urllib.parse import urlparse
 logger = logging.getLogger(__name__)

 _UNSAFE_PATHS_ENV = "CREWAI_TOOLS_ALLOW_UNSAFE_PATHS"
+_ALLOWED_DIRS_ENV = "CREWAI_TOOLS_ALLOWED_DIRS"
+
+
+def _get_allowed_roots(
+    base_dir: str | None = None,
+    allowed_dirs: list[str] | None = None,
+) -> list[str]:
+    """Build the deny-by-default set of allowed root directories.
+
+    Roots are drawn from, in order:
+
+    1. ``base_dir`` (defaults to the current working directory),
+    2. the ``CREWAI_TOOLS_ALLOWED_DIRS`` environment variable, split on
+       ``os.pathsep``,
+    3. the caller-supplied ``allowed_dirs`` list.
+
+    Every root is resolved with :func:`os.path.realpath` so a symlinked root
+    is compared by its real location. Empty entries are ignored and duplicates
+    are collapsed while preserving order. The first element is always the
+    primary root used to resolve relative candidate paths.
+
+    The filesystem root (``os.sep``, e.g. ``"/"``) is never accepted as an
+    *implicitly defaulted* root. When ``base_dir`` is not supplied and the
+    current working directory is ``/`` -- common in containers started without
+    a ``WORKDIR`` -- defaulting to it would make every absolute path "within"
+    the allow-list and disable confinement entirely. In that case the cwd
+    default is dropped; an operator who genuinely wants the whole filesystem
+    must opt in explicitly via ``base_dir``, ``allowed_dirs``, or
+    ``CREWAI_TOOLS_ALLOWED_DIRS``. If no usable root remains, a ``ValueError``
+    is raised rather than silently allowing everything.
+    """
+    primary_explicit = base_dir is not None
+    primary = base_dir if base_dir is not None else os.getcwd()
+
+    # (root, is_explicit) -- explicit roots are operator-provided and may
+    # legitimately include the filesystem root as an opt-in.
+    raw_roots: list[tuple[str, bool]] = [(primary, primary_explicit)]
+
+    env_dirs = os.environ.get(_ALLOWED_DIRS_ENV, "")
+    if env_dirs:
+        raw_roots.extend((d, True) for d in env_dirs.split(os.pathsep) if d)
+
+    if allowed_dirs:
+        raw_roots.extend((d, True) for d in allowed_dirs if d)
+
+    resolved: list[str] = []
+    seen: set[str] = set()
+    for root, is_explicit in raw_roots:
+        real = os.path.realpath(root)
+        if real == os.sep and not is_explicit:
+            # Refuse to let an unconfigured cwd of "/" open the whole filesystem.
+            continue
+        if real not in seen:
+            seen.add(real)
+            resolved.append(real)
+
+    if not resolved:
+        raise ValueError(
+            "No safe allowed directory could be determined: the current working "
+            f"directory is the filesystem root ('{os.sep}'). Set "
+            f"{_ALLOWED_DIRS_ENV} to an explicit directory, pass "
+            f"base_dir/allowed_dirs, or set {_UNSAFE_PATHS_ENV}=true to bypass "
+            "path validation."
+        )
+    return resolved
+
+
+def _is_within_root(resolved_path: str, resolved_root: str) -> bool:
+    """Return True if *resolved_path* equals *resolved_root* or lives beneath it.
+
+    When ``resolved_root`` already ends with a separator (e.g. the filesystem
+    root ``"/"``), appending ``os.sep`` would double it, so the root is used
+    as-is for the prefix in that case.
+    """
+    prefix = resolved_root if resolved_root.endswith(os.sep) else resolved_root + os.sep
+    return resolved_path == resolved_root or resolved_path.startswith(prefix)


 def format_path_for_display(path: str, base_dir: str | None = None) -> str:
@@ -52,21 +128,32 @@ def _is_escape_hatch_enabled() -> bool:
    return os.environ.get(_UNSAFE_PATHS_ENV, "").lower() in ("true", "1", "yes")


-def validate_file_path(path: str, base_dir: str | None = None) -> str:
+def validate_file_path(
+    path: str,
+    base_dir: str | None = None,
+    *,
+    allowed_dirs: list[str] | None = None,
+) -> str:
    """Validate that a file path is safe to read.

    Resolves symlinks and ``..`` components, then checks that the resolved
-    path falls within *base_dir* (defaults to the current working directory).
+    path falls within at least one allowed root directory. The allow-list is
+    built from *base_dir* (defaults to the current working directory), the
+    ``CREWAI_TOOLS_ALLOWED_DIRS`` environment variable, and *allowed_dirs* —
+    see :func:`_get_allowed_roots`. Access is denied by default for anything
+    outside that set.

    Args:
        path: The file path to validate.
-        base_dir: Allowed root directory. Defaults to ``os.getcwd()``.
+        base_dir: Primary allowed root. Defaults to ``os.getcwd()`` and is
+            used to resolve relative ``path`` values.
+        allowed_dirs: Additional allowed root directories.

    Returns:
        The resolved, validated absolute path.

    Raises:
-        ValueError: If the path escapes the allowed directory.
+        ValueError: If the path escapes every allowed directory.
    """
    if _is_escape_hatch_enabled():
        logger.warning(
@@ -76,30 +163,30 @@ def validate_file_path(path: str, base_dir: str | None = None) -> str:
        )
        return os.path.realpath(path)

-    if base_dir is None:
-        base_dir = os.getcwd()
+    allowed_roots = _get_allowed_roots(base_dir, allowed_dirs)
+    primary_root = allowed_roots[0]

-    resolved_base = os.path.realpath(base_dir)
    resolved_path = os.path.realpath(
-        os.path.join(resolved_base, path) if not os.path.isabs(path) else path
+        path if os.path.isabs(path) else os.path.join(primary_root, path)
    )

-    # Ensure the resolved path is within the base directory.
-    # When resolved_base already ends with a separator (e.g. the filesystem
-    # root "/"), appending os.sep would double it ("//"), so use the base
-    # as-is in that case.
-    prefix = resolved_base if resolved_base.endswith(os.sep) else resolved_base + os.sep
-    if not resolved_path.startswith(prefix) and resolved_path != resolved_base:
-        raise ValueError(
-            f"Path '{format_path_for_display(resolved_path, resolved_base)}' is "
-            f"outside the allowed directory. "
-            f"Set {_UNSAFE_PATHS_ENV}=true to bypass this check."
-        )
+    if any(_is_within_root(resolved_path, root) for root in allowed_roots):
+        return resolved_path

-    return resolved_path
+    raise ValueError(
+        f"Path '{format_path_for_display(resolved_path, primary_root)}' is "
+        f"outside the allowed directories. "
+        f"Add the directory via {_ALLOWED_DIRS_ENV}, or set "
+        f"{_UNSAFE_PATHS_ENV}=true to bypass this check."
+    )


-def validate_directory_path(path: str, base_dir: str | None = None) -> str:
+def validate_directory_path(
+    path: str,
+    base_dir: str | None = None,
+    *,
+    allowed_dirs: list[str] | None = None,
+) -> str:
    """Validate that a directory path is safe to read.

    Same as :func:`validate_file_path` but also checks that the path
@@ -107,15 +194,16 @@ def validate_directory_path(path: str, base_dir: str | None = None) -> str:

    Args:
        path: The directory path to validate.
-        base_dir: Allowed root directory. Defaults to ``os.getcwd()``.
+        base_dir: Primary allowed root. Defaults to ``os.getcwd()``.
+        allowed_dirs: Additional allowed root directories.

    Returns:
        The resolved, validated absolute path.

    Raises:
-        ValueError: If the path escapes the allowed directory or is not a directory.
+        ValueError: If the path escapes every allowed directory or is not a directory.
    """
-    validated = validate_file_path(path, base_dir)
+    validated = validate_file_path(path, base_dir, allowed_dirs=allowed_dirs)
    if not os.path.isdir(validated):
        raise ValueError(f"Path '{validated}' is not a directory.")
    return validated
--- a/lib/crewai-tools/src/crewai_tools/tools/file_writer_tool/file_writer_tool.py
+++ b/lib/crewai-tools/src/crewai_tools/tools/file_writer_tool/file_writer_tool.py
@@ -1,5 +1,4 @@
 import os
-from pathlib import Path
 from typing import Any

 from crewai.tools import BaseTool
@@ -8,6 +7,7 @@ from pydantic import BaseModel
 from crewai_tools.security.safe_path import (
    format_error_for_display,
    format_path_for_display,
+    validate_file_path,
 )


@@ -41,22 +41,27 @@ class FileWriterTool(BaseTool):

            filepath = os.path.join(directory, filename)

-            # Prevent path traversal: the resolved path must be strictly inside
-            # filename, and symlink escapes regardless of how directory is set.
-            # is_relative_to() does a proper path-component comparison that is
-            # safe on case-insensitive filesystems and avoids the "// " edge case
-            # We also reject the case where filepath resolves to the directory
-            # itself, since that is not a valid file target.
-            real_directory = Path(directory).resolve()
-            real_filepath = Path(filepath).resolve()
-            display_filepath = format_path_for_display(
-                str(real_filepath), str(real_directory)
-            )
-            if (
-                not real_filepath.is_relative_to(real_directory)
-                or real_filepath == real_directory
-            ):
-                return "Error: Invalid file path — the filename must not escape the target directory."
+            # Confine the resolved write target to an allow-listed root
+            # (cwd + CREWAI_TOOLS_ALLOWED_DIRS), NOT merely inside the
+            # caller-supplied `directory`. That value is itself untrusted when
+            # an LLM tool call chooses it, so checking containment against it
+            # would let an agent write anywhere (e.g. ~/.ssh/authorized_keys).
+            # validate_file_path resolves symlinks and ".." before checking.
+            try:
+                real_filepath = validate_file_path(filepath)
+            except ValueError as e:
+                return f"Error: {format_error_for_display(e)}"
+
+            real_directory = os.path.dirname(real_filepath)
+            display_filepath = format_path_for_display(real_filepath, real_directory)
+
+            # A target that resolves to an existing directory is not a valid
+            # file destination.
+            if os.path.isdir(real_filepath):
+                return (
+                    "Error: Invalid file path — the target must be a file, "
+                    "not a directory."
+                )

            if kwargs.get("directory"):
                os.makedirs(real_directory, exist_ok=True)
--- a/lib/crewai-tools/tests/tools/test_file_writer_tool.py
+++ b/lib/crewai-tools/tests/tools/test_file_writer_tool.py
@@ -17,12 +17,23 @@ def temp_env():
    test_file = "test.txt"
    test_content = "Hello, World!"

+    # FileWriterTool confines writes to an allow-listed root (cwd plus
+    # CREWAI_TOOLS_ALLOWED_DIRS). Explicitly permit this temp dir — this is the
+    # supported way for a developer to widen the write scope to an external
+    # directory, and lets the happy-path tests below write into it.
+    prev_allowed = os.environ.get("CREWAI_TOOLS_ALLOWED_DIRS")
+    os.environ["CREWAI_TOOLS_ALLOWED_DIRS"] = temp_dir
+
    yield {
        "temp_dir": temp_dir,
        "test_file": test_file,
        "test_content": test_content,
    }

+    if prev_allowed is None:
+        os.environ.pop("CREWAI_TOOLS_ALLOWED_DIRS", None)
+    else:
+        os.environ["CREWAI_TOOLS_ALLOWED_DIRS"] = prev_allowed
    shutil.rmtree(temp_dir, ignore_errors=True)


@@ -196,3 +207,24 @@ def test_blocks_symlink_escape(tool, temp_env):
        assert not os.path.exists(outside_file)
    finally:
        shutil.rmtree(outside_dir, ignore_errors=True)
+
+
+
+def test_blocks_unbounded_directory_arg(tool, temp_env):
+    # The core fix: the `directory` argument is itself untrusted (LLM-chosen).
+    # A directory outside the allow-list must be rejected even when filename
+    # is benign — previously this let an agent write anywhere on disk
+    # (e.g. ~/.ssh/authorized_keys).
+    outside_dir = tempfile.mkdtemp()  # NOT added to CREWAI_TOOLS_ALLOWED_DIRS
+    outside_file = os.path.join(outside_dir, "test.txt")
+    try:
+        result = tool._run(
+            filename="test.txt",
+            directory=outside_dir,
+            content="should not be written",
+            overwrite=True,
+        )
+        assert "Error" in result
+        assert not os.path.exists(outside_file)
+    finally:
+        shutil.rmtree(outside_dir, ignore_errors=True)
--- a/lib/crewai-tools/tests/utilities/test_safe_path.py
+++ b/lib/crewai-tools/tests/utilities/test_safe_path.py
@@ -32,12 +32,12 @@ class TestValidateFilePath:

    def test_rejects_dotdot_traversal(self, tmp_path):
        """Reject ../ traversal that escapes base_dir."""
-        with pytest.raises(ValueError, match="outside the allowed directory"):
+        with pytest.raises(ValueError, match="outside the allowed director"):
            validate_file_path("../../etc/passwd", str(tmp_path))

    def test_rejects_absolute_path_outside_base(self, tmp_path):
        """Reject absolute path outside base_dir."""
-        with pytest.raises(ValueError, match="outside the allowed directory"):
+        with pytest.raises(ValueError, match="outside the allowed directories"):
            validate_file_path("/etc/passwd", str(tmp_path))

    def test_allows_absolute_path_inside_base(self, tmp_path):
@@ -50,7 +50,7 @@ class TestValidateFilePath:
        """Reject symlinks that point outside base_dir."""
        link = tmp_path / "sneaky_link"
        os.symlink("/etc/passwd", str(link))
-        with pytest.raises(ValueError, match="outside the allowed directory"):
+        with pytest.raises(ValueError, match="outside the allowed directories"):
            validate_file_path("sneaky_link", str(tmp_path))

    def test_defaults_to_cwd(self):
@@ -113,7 +113,7 @@ class TestValidateDirectoryPath:
            validate_directory_path("file.txt", str(tmp_path))

    def test_rejects_traversal(self, tmp_path):
-        with pytest.raises(ValueError, match="outside the allowed directory"):
+        with pytest.raises(ValueError, match="outside the allowed directories"):
            validate_directory_path("../../", str(tmp_path))


@@ -191,3 +191,95 @@ class TestValidateUrl:
        # file:// would normally be blocked
        result = validate_url("file:///etc/passwd")
        assert result == "file:///etc/passwd"
+
+
+
+class TestAllowList:
+    """Tests for the configurable deny-by-default allow-list of roots."""
+
+    def test_param_extends_allowed_roots(self, tmp_path):
+        """A directory passed via allowed_dirs is permitted."""
+        extra = tmp_path / "extra"
+        extra.mkdir()
+        (extra / "data.txt").touch()
+        result = validate_file_path(
+            str(extra / "data.txt"),
+            base_dir=str(tmp_path / "base"),
+            allowed_dirs=[str(extra)],
+        )
+        assert result == str(extra / "data.txt")
+
+    def test_env_extends_allowed_roots(self, tmp_path, monkeypatch):
+        """A directory listed in CREWAI_TOOLS_ALLOWED_DIRS is permitted."""
+        base = tmp_path / "base"
+        base.mkdir()
+        extra = tmp_path / "extra"
+        extra.mkdir()
+        (extra / "data.txt").touch()
+        monkeypatch.setenv("CREWAI_TOOLS_ALLOWED_DIRS", str(extra))
+        result = validate_file_path(str(extra / "data.txt"), base_dir=str(base))
+        assert result == str(extra / "data.txt")
+
+    def test_denied_without_allow_listing(self, tmp_path, monkeypatch):
+        """The same external dir is rejected when not allow-listed."""
+        base = tmp_path / "base"
+        base.mkdir()
+        extra = tmp_path / "extra"
+        extra.mkdir()
+        (extra / "data.txt").touch()
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOWED_DIRS", raising=False)
+        with pytest.raises(ValueError, match="outside the allowed directories"):
+            validate_file_path(str(extra / "data.txt"), base_dir=str(base))
+
+    def test_multiple_env_roots(self, tmp_path, monkeypatch):
+        """Multiple os.pathsep-separated roots are each honored."""
+        base = tmp_path / "base"
+        base.mkdir()
+        a = tmp_path / "a"
+        a.mkdir()
+        b = tmp_path / "b"
+        b.mkdir()
+        (a / "fa.txt").touch()
+        (b / "fb.txt").touch()
+        monkeypatch.setenv(
+            "CREWAI_TOOLS_ALLOWED_DIRS", os.pathsep.join([str(a), str(b)])
+        )
+        assert validate_file_path(str(a / "fa.txt"), base_dir=str(base)) == str(
+            a / "fa.txt"
+        )
+        assert validate_file_path(str(b / "fb.txt"), base_dir=str(base)) == str(
+            b / "fb.txt"
+        )
+
+    def test_cwd_root_default_is_not_an_allowed_root(self, tmp_path, monkeypatch):
+        """An unconfigured cwd of '/' must not open the whole filesystem.
+
+        Regression for the deny-by-default allow-list silently defaulting to the
+        filesystem root in containers started without a WORKDIR.
+        """
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOWED_DIRS", raising=False)
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOW_UNSAFE_PATHS", raising=False)
+        monkeypatch.setattr(os, "getcwd", lambda: os.sep)
+        with pytest.raises(ValueError, match="filesystem root"):
+            validate_file_path("/etc/passwd")
+
+    def test_cwd_root_with_explicit_allowed_dirs_confines(
+        self, tmp_path, monkeypatch
+    ):
+        """With cwd '/', confinement falls back to the explicit allow-list."""
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOWED_DIRS", raising=False)
+        monkeypatch.setattr(os, "getcwd", lambda: os.sep)
+        (tmp_path / "data.txt").touch()
+        assert validate_file_path(
+            str(tmp_path / "data.txt"), allowed_dirs=[str(tmp_path)]
+        ) == str(tmp_path / "data.txt")
+        with pytest.raises(ValueError, match="outside the allowed directories"):
+            validate_file_path("/etc/passwd", allowed_dirs=[str(tmp_path)])
+
+    def test_explicit_base_dir_root_is_opt_in(self, monkeypatch):
+        """An explicit base_dir of '/' is honored as a deliberate opt-in."""
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOWED_DIRS", raising=False)
+        monkeypatch.delenv("CREWAI_TOOLS_ALLOW_UNSAFE_PATHS", raising=False)
+        assert validate_file_path("/etc/passwd", base_dir=os.sep) == os.path.realpath(
+            "/etc/passwd"
+        )
--- a/lib/crewai/pyproject.toml
+++ b/lib/crewai/pyproject.toml
@@ -8,8 +8,8 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "crewai-core==1.14.8a4",
-    "crewai-cli==1.14.8a4",
+    "crewai-core==1.14.8a5",
+    "crewai-cli==1.14.8a5",
    # Core Dependencies
    "pydantic>=2.11.9,<2.13",
    "openai>=2.30.0,<3",
@@ -55,7 +55,7 @@ Repository = "https://github.com/crewAIInc/crewAI"

 [project.optional-dependencies]
 tools = [
-    "crewai-tools==1.14.8a4",
+    "crewai-tools==1.14.8a5",
 ]
 embeddings = [
    "tiktoken>=0.8.0,<0.13"
--- a/lib/crewai/src/crewai/init.py
+++ b/lib/crewai/src/crewai/init.py
@@ -48,7 +48,7 @@ def _suppress_pydantic_deprecation_warnings() -> None:

 _suppress_pydantic_deprecation_warnings()

-__version__ = "1.14.8a4"
+__version__ = "1.14.8a5"

 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
    "Memory": ("crewai.memory.unified_memory", "Memory"),
--- a/lib/crewai/src/crewai/experimental/agent_executor.py
+++ b/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,
@@ -276,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."""
--- a/lib/crewai/src/crewai/flow/flow.py
+++ b/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_",
--- a/lib/crewai/src/crewai/flow/runtime/init.py
+++ b/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
@@ -35,10 +31,8 @@ from typing import (
    Generic,
    Literal,
    ParamSpec,
-    SupportsIndex,
    TypeVar,
    cast,
-    overload,
 )
 from uuid import uuid4

@@ -123,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,
@@ -137,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:
@@ -227,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]:
@@ -284,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
@@ -299,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

@@ -366,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,
@@ -1008,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)
@@ -1930,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]:
@@ -3600,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

--- a/lib/crewai/src/crewai/flow/runtime/_actions.py
+++ b/lib/crewai/src/crewai/flow/runtime/_actions.py
@@ -24,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:
@@ -103,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(
--- a/lib/crewai/src/crewai/flow/runtime/_refs.py
+++ b/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
--- a/lib/crewai/src/crewai/project/json_loader.py
+++ b/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] = {}


--- a/lib/crewai/src/crewai/utilities/declarative_refs.py
+++ b/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
--- a/lib/crewai/tests/agents/test_agent_executor.py
+++ b/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()
--- a/lib/crewai/tests/project/test_json_loader.py
+++ b/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,
--- a/lib/crewai/tests/test_flow.py
+++ b/lib/crewai/tests/test_flow.py
@@ -1510,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()
@@ -1554,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():
--- a/lib/crewai/tests/test_flow_conversation.py
+++ b/lib/crewai/tests/test_flow_conversation.py
@@ -928,8 +928,6 @@ class TestConversationalFlow:
            conversational = True

        flow = BareChat()
-        # ``flow.state`` returns a ``StateProxy``; the underlying state is
-        # on ``flow._state``. Both views expose the same chat-shaped fields.
        assert isinstance(flow._state, ConversationState)
        assert flow.state.messages == []
        assert flow.state.current_user_message is None
--- a/lib/crewai/tests/test_flow_from_definition.py
+++ b/lib/crewai/tests/test_flow_from_definition.py
@@ -357,6 +357,27 @@ methods:
    listen: begin
 """

+JSON_SCHEMA_REQUIRED_INPUT_STATE_YAML = """
+schema: crewai.flow/v1
+name: JsonSchemaRequiredInputStateFlow
+state:
+  type: json_schema
+  json_schema:
+    title: LeadState
+    type: object
+    required:
+      - lead_name
+    properties:
+      lead_name:
+        type: string
+methods:
+  begin:
+    start: true
+    do:
+      call: expression
+      expr: state.lead_name
+"""
+
 PYDANTIC_REF_WITH_SCHEMA_FALLBACK_YAML = f"""
 schema: crewai.flow/v1
 name: SchemaFallbackFlow
@@ -445,7 +466,8 @@ def _run_with_events(flow, inputs=None):


 def _state_without_id(flow):
-    snapshot = dict(flow.state.model_dump())
+    state = flow.state
+    snapshot = dict(state if isinstance(state, dict) else state.model_dump())
    snapshot.pop("id", None)
    return snapshot

@@ -2298,6 +2320,18 @@ def test_json_schema_state_validates_inputs():
        flow.kickoff(inputs={"count": "not-a-number"})


+def test_json_schema_state_required_fields_can_come_from_kickoff_inputs():
+    flow = Flow.from_definition(
+        FlowDefinition.from_declaration(contents=JSON_SCHEMA_REQUIRED_INPUT_STATE_YAML)
+    )
+
+    result = flow.kickoff(inputs={"lead_name": "Ada Lovelace"})
+
+    assert result == "Ada Lovelace"
+    assert flow.state.lead_name == "Ada Lovelace"
+    assert flow.state.id
+
+
 def test_pydantic_state_falls_back_to_json_schema_when_ref_unimportable():
    flow = Flow.from_definition(
        FlowDefinition.from_declaration(contents=PYDANTIC_REF_WITH_SCHEMA_FALLBACK_YAML)
--- a/lib/crewai/tests/test_flow_persistence.py
+++ b/lib/crewai/tests/test_flow_persistence.py
@@ -233,7 +233,7 @@ def test_persistence_with_base_model(tmp_path):
    assert message.role == "user"
    assert message.type == "text"
    assert message.content == "Hello, World!"
-    assert isinstance(flow.state._unwrap(), State)
+    assert isinstance(flow.state, State)


 def test_fork_with_restore_from_state_id(tmp_path):
--- a/lib/devtools/src/crewai_devtools/init.py
+++ b/lib/devtools/src/crewai_devtools/init.py
@@ -1,3 +1,3 @@
 """CrewAI development tools."""

-__version__ = "1.14.8a4"
+__version__ = "1.14.8a5"
Author	SHA1	Message	Date
Rip&Tear	86c1b37d49	Merge branch 'main' into fix/file-tools-path-allowlist	2026-06-25 12:02:07 +08:00
Rip&Tear	01fc389d4a	Restrict docs broken-links workflow permissions (#6330 ) Some checks failed CodeQL Advanced / Analyze (actions) (push) Has been cancelled Details CodeQL Advanced / Analyze (python) (push) Has been cancelled Details Vulnerability Scan / pip-audit (push) Has been cancelled Details Mark stale issues and pull requests / stale (push) Has been cancelled Details	2026-06-25 10:52:33 +08:00
Vinicius Brasil	178c2d212c	docs: snapshot and changelog for v1.14.8a5 (#6329 ) Some checks failed CodeQL Advanced / Analyze (actions) (push) Has been cancelled Details CodeQL Advanced / Analyze (python) (push) Has been cancelled Details Vulnerability Scan / pip-audit (push) Has been cancelled Details Check Documentation Broken Links / Check broken links (push) Has been cancelled Details Nightly Canary Release / Check for new commits (push) Has been cancelled Details Nightly Canary Release / Build nightly packages (push) Has been cancelled Details Nightly Canary Release / Publish nightly to PyPI (push) Has been cancelled Details	2026-06-24 17:31:32 -07:00
Vinicius Brasil	563b55f7ca	feat: bump versions to 1.14.8a5 (#6328 )	2026-06-24 17:25:08 -07:00
Vinicius Brasil	340d23ae5d	Remove `StateProxy` from flow state access (#6327 ) `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)	2026-06-24 16:37:51 -07:00
Vinicius Brasil	7738a1d30c	Make declarative refs work across flows and crews (#6326 ) Declarative flows already used `module:qualname` refs for runtime objects, but crew JSON tools still had their own lookup path. That meant examples like `project_tools:LookupTool` were treated as named `crewai_tools` lookups and failed with guidance that only mentioned `SerperDevTool` or `custom:<name>`. Invalid refs such as `not_tools:NotATool` also missed the same BaseTool validation used by flow tool actions. Move ref resolution into a shared declarative helper, use it from flow tool actions and crew JSON loading, and require tool refs to resolve to `BaseTool` classes before instantiation. Validation still checks tool refs structurally, so validating a crew does not import or execute project code.	2026-06-24 15:11:59 -07:00
Vinicius Brasil	156b3500b4	Fix JSON schema flow state kickoff inputs (#6325 ) Allow required JSON schema state fields to be supplied by kickoff inputs instead of requiring every field to exist in state.default before runtime. Example: a flow with required lead_name and no state.default can now run with kickoff inputs={"lead_name": "Ada Lovelace"}.	2026-06-24 13:55:38 -07:00
Jesse Miller	5827abbc17	docs: nest One Card per Step under Crew Studio and drop rollout banner (AGE-107) (#6317 ) Some checks failed CodeQL Advanced / Analyze (actions) (push) Has been cancelled Details CodeQL Advanced / Analyze (python) (push) Has been cancelled Details Check Documentation Broken Links / Check broken links (push) Has been cancelled Details Vulnerability Scan / pip-audit (push) Has been cancelled Details The page itself already landed on main via #6247. This rebases onto main and applies the two remaining changes: - Nest crew-studio + merged-step-card into a collapsible "Crew Studio" nav group (pencil icon), across edge and v1.14.7 in en, pt-BR, ko, ar. - Remove the temporary "Rolling out" Note banner (feature ships today). Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-24 13:36:49 -04:00
Rip&Tear	ee6e54233a	docs: document FileWriterTool path confinement and CREWAI_TOOLS_ALLOWED_DIRS Document the deny-by-default allow-list behavior, the new CREWAI_TOOLS_ALLOWED_DIRS env var for extending allowed roots, the fail-closed behavior when cwd is the filesystem root, and the CREWAI_TOOLS_ALLOW_UNSAFE_PATHS escape hatch. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-20 11:45:36 +08:00
Rip&Tear	3bce3cceed	fix: never default the path allow-list to the filesystem root _get_allowed_roots defaulted its primary root to os.getcwd(). In a container started without a WORKDIR, cwd is "/", and since "/" is a parent of every absolute path the deny-by-default allow-list then permitted the entire filesystem -- silently disabling confinement and re-opening arbitrary LLM-controlled file read/write (the exact hole this PR closes). Distinguish an implicitly defaulted primary root (base_dir is None -> os.getcwd()) from operator-provided roots (base_dir, allowed_dirs, CREWAI_TOOLS_ALLOWED_DIRS). When the implicit cwd default resolves to os.sep it is dropped; an explicit "/" is still honored as a deliberate opt-in. If no usable root remains, raise a clear ValueError instead of allowing everything. Addresses the corridor-security review finding on #6248. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-20 11:22:29 +08:00
Rip&Tear	bdb763bfde	Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>	2026-06-20 11:11:54 +08:00
Rip&Tear	5c9436d368	Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>	2026-06-20 11:11:37 +08:00
Rip&Tear	4877828264	Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>	2026-06-20 11:11:24 +08:00
Rip&Tear	685ea13c3b	Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>	2026-06-20 11:11:01 +08:00
Rip&Tear	b70c74e17b	Merge branch 'main' into fix/file-tools-path-allowlist	2026-06-20 11:00:47 +08:00
Rip&Tear	e0df891bdd	fix: confine file tools to an allow-listed root to block path traversal LLM/prompt-injection-controlled file paths could escape the working directory. The RAG search tools and FileReadTool already routed through validate_file_path, but FileWriterTool only checked that `filename` did not escape the caller-supplied `directory` — and `directory` is itself LLM-controlled, so an agent fed untrusted content could be steered into writing anywhere on disk (e.g. ~/.ssh/authorized_keys). - safe_path: replace the single base_dir cwd jail with a deny-by-default allow-list of roots, sourced from cwd + CREWAI_TOOLS_ALLOWED_DIRS + a caller-passed allowed_dirs. Backward compatible for existing callers. - FileWriterTool: route the resolved write target through validate_file_path so writes are confined to an allow-listed root regardless of the directory argument. - Tests: allow-list extension via env/param, deny-by-default, multi-root, and a regression test for the unbounded-directory write. BREAKING: FileWriterTool no longer writes to arbitrary absolute directories by default. Set CREWAI_TOOLS_ALLOWED_DIRS to permit out-of-cwd writes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-20 01:29:19 +08:00