feat(agent): expose approval_callback in create_agent() — human-in-the-loop unusable via public API

[caoergou]

Problem

AgentMiddleware has a fully-implemented human-in-the-loop approval flow: when a SafetyRule returns PermissionResult.NEEDS_APPROVAL, the middleware calls an ApprovalCallback to get user confirmation before executing the tool call.

The infrastructure is all there:

• AgentMiddleware.__init__ accepts approval_callback: ApprovalCallback | None
• AgentMiddleware.awrap_tool_call uses it correctly
• LangChainSubagentRunner.__init__ accepts and forwards it to subagent middleware
• test_middleware.py tests it

But create_agent() — the only public entry point — never accepts or passes this parameter. Users have no way to enable human-in-the-loop approval without forking the factory.

Root Cause

In langchain/agent.py, steps 8 and 13 both omit approval_callback:

# Step 8 — LangChainSubagentRunner is constructed without approval_callback
runner = LangChainSubagentRunner(
    ...,
    permission_gate=permission_gate,
    # approval_callback not passed
)

# Step 13 — AgentMiddleware is constructed without approval_callback
middleware = AgentMiddleware(
    ...,
    permission_gate=permission_gate,
    # approval_callback not passed
)

Proposed Fix

Add approval_callback: ApprovalCallback | None = None to create_agent() and thread it through:

async def create_agent(
    model,
    computer,
    *,
    ...
    approval_callback: ApprovalCallback | None = None,  # ← add this
) -> Agent:

Then pass it in steps 8 and 13. Three lines of change total.

Impact

Without this fix, any SafetyRule that returns NEEDS_APPROVAL silently denies the tool call (see middleware.py line ~502: if self._approval_callback is None: return _create_denied_response(...)). Users cannot implement interactive approval flows using the public API.

Alternatives

None — the workaround requires accessing private internals.

[rpelevin]

This looks like the right public API gap to close, and I would preserve one invariant while threading the callback through: the callback should receive a stable tool-call envelope, not only a loose tool name and args object.

If create_agent() exposes approval_callback, the callback contract should probably include:

• run/session id;
• agent or subagent id;
• tool call id;
• tool name;
• canonical args digest;
• risk or safety rule that returned NEEDS_APPROVAL;
• policy/rule version;
• proposed args summary or redacted preview;
• expiry/freshness window.

And it should return a structured decision rather than a bare boolean:

• approved / denied / expired / cancelled;
• decision id;
• approver identity class, if available;
• optional reason.

Tests I would add around the three-line fix:

1. create_agent(approval_callback=...) passes the callback into both top-level middleware and LangChainSubagentRunner.
2. a rule returning NEEDS_APPROVAL calls the callback before the tool handler runs.
3. no callback keeps the current fail-closed behavior, but returns an explicit approval-required denial reason.
4. approval for one tool call id cannot resume another call with changed args or a different tool name.
5. callback exception or timeout fails closed without executing the tool.

That keeps the public API small while making HITL approval usable as a real pre-execution control boundary.

[caoergou]

Hi @rpelevin, thanks for the thorough write-up — the structured envelope and decision object you've outlined is exactly the kind of design that would make HITL approval production-ready rather than just a prototype hook.

PR #31 intentionally takes the minimal path: wire the parameter through so the flow isn't silently broken for anyone who tries to use it today. The ApprovalCallback type is already defined upstream; this PR just makes it reachable.

I agree the richer contract you're describing — stable envelope with audit fields, structured decision return, token-scoped approval — is the right long-term direction. I'd suggest tracking that in a follow-on issue so it gets the design discussion it deserves without blocking the bug fix.

@Andy-hhh-hub @xuelin-cell: does the current scope of #31 work for you, or would you prefer we fold the envelope design in here?