[FEATURE] Tool-Level Human-in-the-Loop (HITL) for Sensitive Action approval

[AryanSharma21]

Feature Area

Core functionality

Is your feature request related to a an existing bug? Please link it here.

Problem: Currently, the Crew AI system handles the HITL interctions on the task level, once the model runs a query, the execution of different tasks within the query are operated. In many real world scenarios the tasks can have different level of sensitivity as follows:

Case 1: Scrap data from kaggle and create a summary of statistical features of the data.

In this case, there is no sensitive execution as of now, the model performs as per the query, requires no additional approval.

Case 2: Analyze the transaction pattern and freeze the crypto wallet.

In such cases, where there is a high stake or financial executions, a subtle inaccuracy in the prompt or the model understanding can cause the model to freeze a wallet or make a bigger wire transfer [for example].

Describe the solution you'd like

The solution is to propose a parameter called "requires_human_approval" directly inside the tool decorator, which defaults to "false" for base cases such as case 1, and can be set as true for sensitive cases like case 2.

When an agent attempts to use a tool with this flag set to True, the execution pauses, shows the user the exact arguments the LLM wants to use, and waits for a Y/n or text feedback. If rejected, the feedback is sent back to the agent as an observation so it can course-correct.

Timeout Fallback: Introduce a human_approval_timeout (e.g., default 60 seconds). If no human responds, the tool safely aborts and returns an "Approval Timeout" observation to the agent.

Callback Support: Allow the approval prompt to trigger a callback function instead of a terminal input(), so developers can route the approval request to a Slack webhook, a Streamlit button, or a custom UI.

Describe alternatives you've considered

None for now, open to alternative ideas as per the feedbacks.

Additional context

Design examples:

Case 1: Default Behavior (Fully Autonomous)

from crewai.tools import tool

# Defaults to False. Runs automatically without pause.
@tool("Kaggle Scraper")
def scrape_kaggle(dataset_url: str):
    """Scrapes statistical features from Kaggle data."""
    return fetch_data(dataset_url)

Case 2:

Case 2: Sensitive Execution (Requires Approval)

# User explicitly opts-in to the safety check
@tool("Freeze Wallet", requires_human_approval=True)
def freeze_wallet(wallet_address: str):
    """Freezes a suspected illicit crypto wallet."""
    return execute_freeze(wallet_address)

Willingness to Contribute

Yes, I'd be happy to submit a pull request

[AryanSharma21]

working on it locally, requesting feedbacks, and maintainer approval

[sattyamjjain]

Hey @AryanSharma21, I built close to this in ferrumdeck (https://github.com/sattyamjjain/ferrumdeck), so here are a few things that bit me. Sharing as prior art; take what's useful.

1. A boolean won't survive contact. requires_human_approval=True on the tool means freeze_wallet pauses the same way whether the LLM filled in a test address or a real one, and transfer_funds pauses for $5 and $5M identically. What happened for me is people turn it off. I'd let the flag take a predicate over the bound arguments, or a risk level, so the decision can see what the LLM actually filled in and not just which tool it picked. That's the one call I'd make before writing the PR; it's hard to change later.

2. The timeout should fail closed, and it should stick. Right now it returns "Approval Timeout" as an observation, so the agent just retries the call, or reaches the same outcome through a different tool. I revoke the capability for the rest of the run instead of aborting the single call. Otherwise it's a speed bump, not a gate.

3. Rejection feedback is an untrusted input. "feedback sent back to the agent as an observation" is free text from a human going straight into agent context, so it needs the same handling as tool output.

4. Write the decision down. Approver, timestamp, the exact bound arguments, approve or deny. Most people who want HITL want it because someone is going to ask them to prove it later. Cheap now, painful to retrofit.

One more thing on the callback: the 60s default won't work for the Slack path since that round trip is minutes. I'd make the approval a resumable object rather than a blocked call; otherwise, terminal input() and webhook end up as two different code paths.

Happy to review the PR when you open it.

[AryanSharma21]

Thanks for the feedback, @sattyamjjain , will be looking closely into this