[FEATURE] GuardrailProvider interface for pre-tool-call authorization

快速结论：该 Issue 是一个功能请求（[FEATURE] GuardrailProvider interface for pre-tool-call authorization），并不是用户运行 CrewAI 时出现的崩溃报错。如果你在寻找”工具调用前授权”的标准接口，这里的结论是：CrewAI 主仓库当时尚未提供标准化的 GuardrailProvider 契约，讨论停留设计层面，没有合并进框架的确认方案。排查时优先确认你所用 CrewAI 版本是否已内置该接口，若没有则只能通过 BeforeToolCallHook 自行封装。

适用环境：Issue 中提及的现有能力为 crewai.hooks.types 下的 BeforeToolCallHook 协议，以及 crewai.hooks.tool_hooks 的 register_before_tool_call_hook。Issue 未提供已确认的 Python、CUDA、PyTorch、显卡或操作系统版本信息。

最快修复方案：暂无确认的一步修复方案。该 Issue 为 Feature Request，未提供合并后的官方实现或安装命令。

注意事项：正文中给出的 GuardrailRequest、GuardrailDecision、GuardrailProvider 及 enable_guardrail 均为提案中的示例代码，属于设计讨论，未必与任何已发布版本一致；async 授权、suspend/resolve 超时策略作者明确表示”尚未完全在提案中指定”。直接照搬可能无法运行。

问题场景

开发者在 CrewAI 中构建多 Agent 系统时，希望在每个工具（tool）被调用之前做统一的授权判断，例如按工具名拒绝 ShellTool、按 Agent 角色限制文件路径、或对每次 crew 运行做工具调用限流。用户发现 CrewAI 现有的 Task.guardrail / Task.guardrails 只在任务完成后校验输出，无法拦截工具调用本身；而 BeforeToolCallHook 虽然能通过返回 False 阻止工具执行，却缺少一个介于 hook 系统与授权逻辑之间的标准 provider 契约。因此提出该 Feature Request，希望引入 provider 无关的 GuardrailProvider 接口。

报错原文

[FEATURE] GuardrailProvider interface for pre-tool-call authorization

原因分析

这不是运行时报错，而是能力缺口。可能原因：CrewAI 现有 guardrail 体系（Task.guardrail / Task.guardrails）的职责是校验任务输出，作用点在任务完成之后；BeforeToolCallHook 提供的是原始 hook 机制，能阻断工具执行但需要用户自行编写 hook 逻辑。两者之间缺少一个可插拔的策略引擎契约，导致用户无法在不写 raw hook 的前提下接入任意授权策略（如策略即代码、审批流、风险打分）。Issue 中引用的多个相关请求（#4502、#4596、#4682、#4840、#4810）也指向同一类工具级授权需求长期未被标准化。

环境排查

确认当前 CrewAI 版本是否已包含 GuardrailProvider 或等价接口：先查 crewai.hooks.types 与 crewai.hooks 下的公开符号。
确认现有 hook 能力是否存在：BeforeToolCallHook 协议与 register_before_tool_call_hook 是否在你的版本中可导入。
确认 GuardrailRequest 中需要的上下文字段（tool_input、agent_role、task_description、crew_id）在你的 hook context 对象上是否有对应属性，提案中使用的是 getattr(context.agent, "role", None) 这类兼容写法。
Issue 未提供 Python、CUDA、PyTorch、显卡或依赖版本信息，这些不构成该问题的影响因素。

解决步骤

先确认需求性质：这是功能请求，不是 bug 修复。若你期望开箱即用的 GuardrailProvider，先确认所用 CrewAI 版本是否已内置；没有内置则需自建。
可优先尝试：按提案思路自行封装。GuardrailProvider 定义为 @runtime_checkable 的 Protocol，包含 name 属性、evaluate(request) 方法和可选的 health_check()。
实现一个 adapter，把 provider 注册为 BeforeToolCallHook：在 hook 内构造 GuardrailRequest，调用 provider.evaluate()，allow 为假时返回 False 阻断工具执行，否则返回 None 放行。
设置 fail-closed 行为：提案中 enable_guardrail(provider, *, fail_closed=True)，当 evaluate 抛异常时，fail_closed 为真则返回 False（默认拒绝），否则返回 None（放行）。这是安全默认值，建议保留。
若涉及异步审批（human-in-the-loop），注意作者在其后的讨论中说明：设计上 provider 的 before_tool_call 可返回 allow、deny 或 suspend，suspend 路径由框架挂起执行并轮询或等待回调，直到 provider 通过 resolve(decision_id, outcome) 解阻塞。但作者明确表示这部分”尚未在提案中完全指定”，不要按最终 API 使用。
若你的场景涉及下游依赖等待被挂起的动作，注意讨论中作者自己也不确定如何干净地接入 crew 架构，这个问题在 Issue 中未解决。
不要照搬 YAML 配置示例（guardrail_provider: 段）作为可用配置，它只是提案中的设想。

验证方法

若你按提案自行实现了 adapter，验证方式是：注册 hook 后调用一个被 provider 判定为拒绝的工具，确认工具未实际执行且 reason 被回传给 Agent；再调用一个判定为允许的工具，确认正常执行。同时验证 fail_closed=True 时 provider 抛异常会阻断调用。由于该接口未合并进官方版本，这里的验证只针对你的自定义实现，不代表 CrewAI 官方行为。若你只是想确认官方是否已支持，检查对应版本源码中是否存在 GuardrailProvider 即可，无需运行时验证。