Skip to main content

recusal-crewai

The Recusal gate for CrewAI: every tool call a crew makes is judged by your policy before the tool runs, and a refused call never runs.

This is a separate distribution from recusal. The kernel has zero runtime dependencies and a frozen compatibility perimeter; this package carries the CrewAI dependency and its own version, so a CrewAI release never forces a release of the kernel.

Status: not yet published to PyPI. Until it is, install it from the repository:

pip install "recusal-crewai @ git+https://github.com/philpaz/recusal#subdirectory=adapters/crewai"

Requires Python 3.10+ (CrewAI's minimum), recusal>=0.14.0 and crewai>=1.15.34. It is tested on every pull request against exactly crewai==1.15.34, and weekly against the newest release.

Use

from recusal import Finding
from recusal_crewai import install_recusal_hooks


def policy(tool_name, tool_input):
    sql = tool_input.get("sql", "")
    if tool_name == "run_sql" and sql.lstrip().upper().startswith("DELETE"):
        return [Finding.fail("no_deletes", severity="CRITICAL", message="DELETE is not allowed")]
    return []


uninstall = install_recusal_hooks(policy)  # after your other hooks
try:
    crew.kickoff()
finally:
    uninstall()

The gate is CrewAI's own tool-call hooks. The before hook judges the call and blocks a refusal; the after hook replaces CrewAI's fixed "Tool execution blocked by hook" line with Recusal's reason, so the model reads why on its next turn. A policy that raises refuses the call (fail closed).

The install is process-global. CrewAI's hook registry covers every agent, task and crew in the process, including a coworker an agent delegates to, and every tool kind CrewAI runs through its hooks.

Install the gate after your other hooks. Hooks run in registration order, and a hook registered after the gate can change the arguments the gate judged.

The policy judges the invocation the tool receives, not the dict the model proposed: omitted defaults are completed from the tool's schema and values are validated once, the same way CrewAI prepares them at execution.

Put every decision on the record

from recusal.audit import AuditLog
from recusal_crewai import install_audited_hooks

log = AuditLog(path="decisions.jsonl")
uninstall = install_audited_hooks(policy, log)

Each call the before hook sees, allowed or refused, is one hash-chained entry labeled crewai.before_tool_call with a SHA-256 fingerprint of the arguments (never the arguments). If the log cannot be written the call is refused. Check the log with recusal audit verify decisions.jsonl.

Entries carry no call id. CrewAI's hook context has no id for the call, so the record does not invent one. Entries are told apart by their order on the chain, the tool, the fingerprint, and control.crewai_agent, the role of the agent that made the call. CrewAI runs one turn's tool calls on a thread pool, so the order of a turn's entries on the chain is not the order the model proposed them.

What the gate refuses, and what it does not see

  • Refused before the policy runs: a tool or schema that is not CrewAI's stock one (a schema with a validator, an alias, a constraint, a default_factory or an intermediate base; a tool class that overrides CrewAI's run or validation methods), an unsupported annotation, an unknown or missing parameter, a validation failure, and a callable that declares a parameter its schema omits.
  • Not judged: what a tool does once it runs. A tool that executes code or shell it is handed needs a policy that names it.
  • Not on the audit log: a call a hook registered before the gate blocked, and whatever a hook registered after the gate changed.

Compatibility

This package is outside the kernel's frozen perimeter (STABILITY.md, Integrations). Its public names are the ones in recusal_crewai.__all__. When a CrewAI release changes what the hooks are handed, this package gets a release and the kernel does not.

A runnable offline demonstration, with a scripted model and no API key, is examples/crewai_gate.py and examples/crewai_audit.py.

Metadata

Release files for recusal-crewai 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for recusal-crewai 0.1.0
File Size Uploaded Provenance Actions
recusal_crewai-0.1.0.tar.gz 17.8 kB With provenance Details for recusal_crewai-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for recusal-crewai 0.1.0
File Interpreter ABI Platform Actions
recusal_crewai-0.1.0-py3-none-any.whl Python 3 none any Details for recusal_crewai-0.1.0-py3-none-any.whl

Total release size: 35.0 kB

Release files / recusal_crewai-0.1.0.tar.gz

Download URL recusal_crewai-0.1.0.tar.gz
Size 17.8 kB
Tags Source
SHA-256 checksum
How to use checksums
20376155b726713391aeefd4adef043ae4a76bde4dd5565e7b97e28ced4f8e9f
BLAKE2b-256 checksum
How to use checksums
8187b330f425bc5a2407d73ff297e69bd9c706189f6c50a9bbb045a787be1761
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / recusal_crewai-0.1.0-py3-none-any.whl

Download URL recusal_crewai-0.1.0-py3-none-any.whl
Size 17.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
91f566885b7f165bd5e00679fc4baa862946e61ad56eb44e0fa154c9fa128f8c
BLAKE2b-256 checksum
How to use checksums
46c732ed27f735de6b4bfd8e9c663faa58a5d18469420784106be86235879721
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for recusal-crewai 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for recusal_crewai-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page