Allow Human-in-the-Loop to review fully materialized tool calls

[Aarkin7]

Is your feature request related to a problem? Please describe.
Yes. When I enable Human-in-the-Loop (HITL), I expect the human reviewer to approve the exact tool call that will actually run. Today that is not always the case.

For tools that use inputs_from_state or otherwise receive values from agent state at execution time, HITL shows only the arguments produced by the model. Additional values are injected later, right before the tool executes. As a result, the human can approve an incomplete view of the action.

This becomes a real safety and auditability problem for sensitive tools such as deleting records, sending emails, or calling tenant-scoped APIs. A reviewer may think they are approving one call, while the tool actually runs with additional hidden parameters.

Describe the solution you'd like
I’d like an opt-in HITL mode where the reviewer can inspect the fully materialized tool call before execution.

In practice, that would mean:

• keep current behavior as the default for backward compatibility
• add an opt-in mode on ConfirmationHook or BlockingConfirmationStrategy
• in that mode, show state-injected values alongside model-provided values
• label where each value came from, for example llm_arg vs state_injected
• support optional redaction rules for sensitive state-derived values
• avoid leaking hidden state back into the LLM-visible transcript after approval

The behavior goal is simple:
what the human sees before approving should match what the tool will actually execute with

If some values are not stable yet because they depend on earlier tool calls in the same step, showing a deferred or read-only placeholder would still be better than showing an incomplete or misleading view.

Describe alternatives you've considered

• One option is to leave the current behavior as-is and rely on documentation, but that does not solve the actual review gap.
• Another option is to avoid inputs_from_state and force the LLM to provide every parameter explicitly. That works in some cases, but it removes the benefit of state injection and may expose internal IDs, tenant context, or other sensitive values to the model when those values were intentionally kept out of the tool schema.
• A third option is to build a custom confirmation layer outside Haystack, but that means reimplementing Haystack’s materialization logic in user code and reduces the usefulness of the built-in HITL workflow.

Additional context
I reproduced the current behavior locally and attached a screenshot.

In the repro:

• agent state contained selected_customer_id = 'cust_84319'
• the HITL prompt showed only reason: duplicate account
• after approval, the tool actually executed with:
• • customer_id = cust_84319
• • reason = duplicate account
• the transcript summary still showed only {'reason': 'duplicate account'} as the tool-call arguments reviewed before execution

So the human approved one representation of the call, but the tool executed with a fuller one. The attached screenshot shows this mismatch directly: the approval prompt contains only the LLM-provided argument, while the execution output immediately after shows the hidden state-injected parameter that was actually used.

This appears to match the current documented behavior, so I’m raising it as an enhancement request rather than a bug report.

[Aarkin7]

Hi @julian-risch, I’d like to work on this enhancement. I’ve reproduced the current behavior locally and have a clear implementation approach in mind. If this sounds good, I’m happy to proceed with a PR.

[sjrl]

Hey @Aarkin7 thanks for opening and for looking into this. I'm happy to give your implementation idea a look but its likely we will want to tackle something like this internally since it will likely need to modify Agent internals.

[Aarkin7]

Makes sense, thanks for looking into it! Happy to share a quick draft PR of the opt-in approach if that's useful, but totally fine if this ends up being handled internally. Let me know either way so I know whether to go ahead with the draft PR.

[renezander030]

The display side of this only closes half the gap. Even with state_injected values labeled at review time, state can change between approval and execution, and the deferred placeholders you mention are exactly where that bites. What has worked for us in production: record a canonical digest of the fully materialized call at approval time, then re-materialize and compare digests right before dispatch, and any mismatch blocks the call and sends it back for review. That also produces the audit artifact for free, because the stored approval now provably matches what actually ran, which matters more to an auditor than what the UI displayed. We ship this as a draft, validate, approve, dispatch pattern here: https://github.com/renezander030/agent-approval-gate