22
33from __future__ import annotations
44
5- from typing import TYPE_CHECKING , Any , Literal , Protocol
5+ import json
6+ from dataclasses import replace
7+ from typing import TYPE_CHECKING , Annotated , Any , Literal , Protocol , cast
68
79from langchain_core .messages import AIMessage , ToolCall , ToolMessage
810from langgraph .config import get_config
911from langgraph .prebuilt .tool_node import ToolRuntime
10- from langgraph .types import interrupt
12+ from langgraph .types import Command , interrupt
1113from typing_extensions import NotRequired , TypedDict
1214
1315from langchain .agents .middleware .types import (
1416 AgentMiddleware ,
1517 AgentState ,
1618 ContextT ,
19+ PrivateStateAttr ,
1720 ResponseT ,
1821 StateT ,
1922 ToolCallRequest ,
2023)
2124
2225if TYPE_CHECKING :
23- from collections .abc import Callable
26+ from collections .abc import Awaitable , Callable
2427
2528 from langgraph .runtime import Runtime
2629
2730
31+ _EDITED_TOOL_CALLS_KEY = "hitl_edited_tool_calls"
32+ """State key mapping tool call ID to the reviewer's replacement for it."""
33+
34+ _EDIT_NOTICE = (
35+ "Note: a human reviewer replaced this tool call before it ran. The call recorded in "
36+ "your message is the one you produced, not the one that executed. This was "
37+ "intentional and authorized. Do not re-issue your original call."
38+ )
39+ """Default text prepended to the result of a tool call a reviewer edited."""
40+
41+
2842class Action (TypedDict ):
2943 """Represents an action with a name and args."""
3044
@@ -216,14 +230,24 @@ def format_tool_description(
216230 """
217231
218232
233+ class _HumanInTheLoopState (AgentState [ResponseT ]):
234+ """State schema for `HumanInTheLoopMiddleware`."""
235+
236+ hitl_edited_tool_calls : NotRequired [Annotated [dict [str , Action ], PrivateStateAttr ]]
237+ """Track tool call edits from `after_model`, so they can be used by `wrap_tool_call`."""
238+
239+
219240class HumanInTheLoopMiddleware (AgentMiddleware [StateT , ContextT , ResponseT ]):
220241 """Human in the loop middleware."""
221242
243+ state_schema = _HumanInTheLoopState # type: ignore[assignment]
244+
222245 def __init__ (
223246 self ,
224247 interrupt_on : dict [str , bool | InterruptOnConfig ],
225248 * ,
226249 description_prefix : str = "Tool execution requires approval" ,
250+ edit_notice : str | None = _EDIT_NOTICE ,
227251 ) -> None :
228252 """Initialize the human in the loop middleware.
229253
@@ -249,6 +273,8 @@ def __init__(
249273 requested.
250274
251275 Not used if a tool has a `description` in its `InterruptOnConfig`.
276+ edit_notice: Text prepended to the result of a tool call a reviewer replaced
277+ via an `edit` decision. Pass `None` to add nothing.
252278
253279 Raises:
254280 ValueError: If a tool's `InterruptOnConfig` does not have a non-empty
@@ -257,6 +283,7 @@ def __init__(
257283 dropped, disabling the approval gate for that tool.
258284 """
259285 super ().__init__ ()
286+ self .edit_notice = edit_notice
260287 resolved_configs : dict [str , InterruptOnConfig ] = {}
261288 for tool_name , tool_config in interrupt_on .items ():
262289 if isinstance (tool_config , bool ):
@@ -326,16 +353,9 @@ def _process_decision(
326353 if decision ["type" ] == "approve" and "approve" in allowed_decisions :
327354 return tool_call , None
328355 if decision ["type" ] == "edit" and "edit" in allowed_decisions :
329- edited_action = decision ["edited_action" ]
330- return (
331- ToolCall (
332- type = "tool_call" ,
333- name = edited_action ["name" ],
334- args = edited_action ["args" ],
335- id = tool_call ["id" ],
336- ),
337- None ,
338- )
356+ # Keep the model's own call in the message; `wrap_tool_call` substitutes the
357+ # reviewer's at execution time.
358+ return tool_call , None
339359 if decision ["type" ] == "reject" and "reject" in allowed_decisions :
340360 reason = decision .get ("message" )
341361 content = (
@@ -444,8 +464,11 @@ def after_model(
444464 review_configs .append (review_config )
445465 interrupt_indices .append (idx )
446466
447- # If no interrupts needed, return early
467+ # If no interrupts needed, return early, dropping any earlier turn's edits so
468+ # they cannot be applied to this turn's tool calls.
448469 if not action_requests :
470+ if state .get (_EDITED_TOOL_CALLS_KEY ):
471+ return {_EDITED_TOOL_CALLS_KEY : {}}
449472 return None
450473
451474 # Create single HITLRequest with all actions and configs
@@ -468,6 +491,7 @@ def after_model(
468491 # Process decisions and rebuild tool calls in original order
469492 revised_tool_calls : list [ToolCall ] = []
470493 artificial_tool_messages : list [ToolMessage ] = []
494+ edited_tool_calls : dict [str , Action ] = {}
471495 decision_idx = 0
472496
473497 for idx , tool_call in enumerate (last_ai_msg .tool_calls ):
@@ -482,6 +506,8 @@ def after_model(
482506 )
483507 if revised_tool_call is not None :
484508 revised_tool_calls .append (revised_tool_call )
509+ if decision ["type" ] == "edit" and (edited_id := revised_tool_call .get ("id" )):
510+ edited_tool_calls [edited_id ] = decision ["edited_action" ]
485511 if tool_message :
486512 artificial_tool_messages .append (tool_message )
487513 else :
@@ -491,7 +517,12 @@ def after_model(
491517 # Update the AI message to only include approved tool calls
492518 last_ai_msg .tool_calls = revised_tool_calls
493519
494- return {"messages" : [last_ai_msg , * artificial_tool_messages ]}
520+ # `wrap_tool_call` reads this back to substitute and annotate the call. Always
521+ # written, so an earlier turn's edits cannot survive into this one.
522+ return {
523+ "messages" : [last_ai_msg , * artificial_tool_messages ],
524+ _EDITED_TOOL_CALLS_KEY : edited_tool_calls ,
525+ }
495526
496527 async def aafter_model (
497528 self , state : AgentState [Any ], runtime : Runtime [ContextT ]
@@ -506,3 +537,144 @@ async def aafter_model(
506537 Updated message with the revised tool calls.
507538 """
508539 return self .after_model (state , runtime )
540+
541+ def _reviewer_edit (self , request : ToolCallRequest ) -> Action | None :
542+ """The reviewer's replacement for this call, if an `edit` decision replaced it."""
543+ tool_call_id = request .tool_call .get ("id" )
544+ if not tool_call_id :
545+ return None
546+ edited = request .state .get (_EDITED_TOOL_CALLS_KEY ) or {}
547+ if tool_call_id in edited :
548+ return cast ("Action" , edited [tool_call_id ])
549+ return None
550+
551+ def _apply_edit (self , request : ToolCallRequest , executed : Action ) -> ToolCallRequest :
552+ """Point the request at the reviewer's call, resolving a redirected tool.
553+
554+ Raises:
555+ ValueError: If the reviewer named a tool the agent does not have.
556+ """
557+ tool_call : ToolCall = {
558+ ** request .tool_call ,
559+ "name" : executed ["name" ],
560+ "args" : executed ["args" ],
561+ }
562+ if executed ["name" ] == request .tool_call ["name" ]:
563+ return request .override (tool_call = tool_call )
564+
565+ # `tool_call["name"]` and `tool` must stay in agreement.
566+ available = request .runtime .tools
567+ tool = next ((t for t in available if t .name == executed ["name" ]), None )
568+ if tool is None :
569+ names = ", " .join (sorted (t .name for t in available ))
570+ msg = (
571+ f"Reviewer edited tool call { request .tool_call ['id' ]!r} to "
572+ f"{ executed ['name' ]!r} , which is not an available tool. "
573+ f"Available tools: { names } ."
574+ )
575+ raise ValueError (msg )
576+ return request .override (tool_call = tool_call , tool = tool )
577+
578+ def _notice (self , executed : Action , * , has_content : bool ) -> str :
579+ """The notice text, stating the call that actually ran."""
580+ notice = (
581+ f"{ self .edit_notice } Executed instead: { executed ['name' ]} with arguments "
582+ f"{ json .dumps (executed ['args' ], default = str )} ."
583+ )
584+ return f"{ notice } \n \n Tool response:" if has_content else notice
585+
586+ def _prepend_notice (self , message : ToolMessage , executed : Action ) -> ToolMessage :
587+ """Return `message` with the reviewer-edit notice prepended to its content."""
588+ if not self .edit_notice :
589+ return message
590+ edit_notice = self ._notice (executed , has_content = bool (message .content ))
591+
592+ content : str | list [str | dict [Any , Any ]]
593+ if isinstance (message .content , str ):
594+ if edit_notice in message .content :
595+ return message
596+ separator = "\n " if message .content else ""
597+ content = f"{ edit_notice } { separator } { message .content } "
598+ else :
599+ if any (edit_notice in str (block ) for block in message .content ):
600+ return message
601+ # Match the surrounding block shape; providers may reject mixed lists.
602+ notice : str | dict [Any , Any ] = (
603+ edit_notice
604+ if message .content and all (isinstance (b , str ) for b in message .content )
605+ else {"type" : "text" , "text" : edit_notice }
606+ )
607+ content = [notice , * message .content ]
608+
609+ return message .model_copy (update = {"content" : content })
610+
611+ def _annotate_edited_result (
612+ self ,
613+ result : ToolMessage | Command [Any ],
614+ request : ToolCallRequest ,
615+ executed : Action | None ,
616+ ) -> ToolMessage | Command [Any ]:
617+ """Tell the model a reviewer replaced the call, and with what."""
618+ if not self .edit_notice or executed is None :
619+ return result
620+
621+ if isinstance (result , ToolMessage ):
622+ return self ._prepend_notice (result , executed )
623+
624+ # A `Command` carries the `ToolMessage` in its state update.
625+ if not isinstance (result , Command ) or not isinstance (result .update , dict ):
626+ return result
627+ messages = result .update .get ("messages" )
628+ if not isinstance (messages , list ):
629+ return result
630+ tool_call_id = request .tool_call .get ("id" )
631+ return replace (
632+ result ,
633+ update = {
634+ ** result .update ,
635+ "messages" : [
636+ self ._prepend_notice (message , executed )
637+ if isinstance (message , ToolMessage ) and message .tool_call_id == tool_call_id
638+ else message
639+ for message in messages
640+ ],
641+ },
642+ )
643+
644+ def wrap_tool_call (
645+ self ,
646+ request : ToolCallRequest ,
647+ handler : Callable [[ToolCallRequest ], ToolMessage | Command [Any ]],
648+ ) -> ToolMessage | Command [Any ]:
649+ """Prepend reviewer-edit guidance to the result of an edited tool call.
650+
651+ Args:
652+ request: The tool call request being executed.
653+ handler: Callable that executes the tool.
654+
655+ Returns:
656+ The tool result, with a note prepended when a reviewer edited the call.
657+ """
658+ executed = self ._reviewer_edit (request )
659+ if executed is not None :
660+ request = self ._apply_edit (request , executed )
661+ return self ._annotate_edited_result (handler (request ), request , executed )
662+
663+ async def awrap_tool_call (
664+ self ,
665+ request : ToolCallRequest ,
666+ handler : Callable [[ToolCallRequest ], Awaitable [ToolMessage | Command [Any ]]],
667+ ) -> ToolMessage | Command [Any ]:
668+ """Async variant of `wrap_tool_call`.
669+
670+ Args:
671+ request: The tool call request being executed.
672+ handler: Awaitable callable that executes the tool.
673+
674+ Returns:
675+ The tool result, with a note prepended when a reviewer edited the call.
676+ """
677+ executed = self ._reviewer_edit (request )
678+ if executed is not None :
679+ request = self ._apply_edit (request , executed )
680+ return self ._annotate_edited_result (await handler (request ), request , executed )
0 commit comments