fix: improving parity with openai-agent-js hitl functionality

Author: mjschock

examples/agent_patterns/human_in_the_loop.py

@@ -113,16 +113,16 @@ async def main():
 
             print("\nTool call details:")
             print(f"  Agent: {interruption.agent.name}")
-            print(f"  Tool: {interruption.raw_item.name}")
-            print(f"  Arguments: {interruption.raw_item.arguments}")
+            print(f"  Tool: {interruption.name}")
+            print(f"  Arguments: {interruption.arguments}")
 
             confirmed = await confirm("\nDo you approve this tool call?")
 
             if confirmed:
-                print(f"✓ Approved: {interruption.raw_item.name}")
+                print(f"✓ Approved: {interruption.name}")
                 state.approve(interruption)
             else:
-                print(f"✗ Rejected: {interruption.raw_item.name}")
+                print(f"✗ Rejected: {interruption.name}")
                 state.reject(interruption)
 
         # Resume execution with the updated state

examples/agent_patterns/human_in_the_loop_stream.py

@@ -94,16 +94,16 @@ async def main():
 
             print("\nTool call details:")
             print(f"  Agent: {interruption.agent.name}")
-            print(f"  Tool: {interruption.raw_item.name}")
-            print(f"  Arguments: {interruption.raw_item.arguments}")
+            print(f"  Tool: {interruption.name}")
+            print(f"  Arguments: {interruption.arguments}")
 
             confirmed = await confirm("\nDo you approve this tool call?")
 
             if confirmed:
-                print(f"✓ Approved: {interruption.raw_item.name}")
+                print(f"✓ Approved: {interruption.name}")
                 state.approve(interruption)
             else:
-                print(f"✗ Rejected: {interruption.raw_item.name}")
+                print(f"✗ Rejected: {interruption.name}")
                 state.reject(interruption)
 
         # Resume execution with streaming

src/agents/_run_impl.py

@@ -356,37 +356,51 @@ async def execute_tools_and_side_effects(
                 config=run_config,
             ),
         )
-        # Check for tool approval interruptions before adding items
+        # Add all tool results to new_step_items first, including approval items.
+        # This ensures ToolCallItem items from processed_response.new_items are preserved
+        # in the conversation history when resuming after an interruption.
         from .items import ToolApprovalItem
 
+        # Add all function results (including approval items) to new_step_items
+        for result in function_results:
+            new_step_items.append(result.run_item)
+
+        # Add all other tool results
+        new_step_items.extend(computer_results)
+        for shell_result in shell_results:
+            new_step_items.append(shell_result)
+        for apply_patch_result in apply_patch_results:
+            new_step_items.append(apply_patch_result)
+        new_step_items.extend(local_shell_results)
+
+        # Check for interruptions after adding all items
         interruptions: list[RunItem] = []
-        approved_function_results = []
         for result in function_results:
             if isinstance(result.run_item, ToolApprovalItem):
                 interruptions.append(result.run_item)
-            else:
-                approved_function_results.append(result)
+        for shell_result in shell_results:
+            if isinstance(shell_result, ToolApprovalItem):
+                interruptions.append(shell_result)
+        for apply_patch_result in apply_patch_results:
+            if isinstance(apply_patch_result, ToolApprovalItem):
+                interruptions.append(apply_patch_result)
 
         # If there are interruptions, return immediately without executing remaining tools
         if interruptions:
-            # Return the interruption step
+            # new_step_items already contains:
+            # 1. processed_response.new_items (added at line 312) - includes ToolCallItem items
+            # 2. All tool results including approval items (added above)
+            # This ensures ToolCallItem items are preserved in conversation history when resuming
             return SingleStepResult(
                 original_input=original_input,
                 model_response=new_response,
                 pre_step_items=pre_step_items,
-                new_step_items=interruptions,
+                new_step_items=new_step_items,
                 next_step=NextStepInterruption(interruptions=interruptions),
                 tool_input_guardrail_results=tool_input_guardrail_results,
                 tool_output_guardrail_results=tool_output_guardrail_results,
                 processed_response=processed_response,
             )
-
-        new_step_items.extend([result.run_item for result in approved_function_results])
-        new_step_items.extend(computer_results)
-        new_step_items.extend(shell_results)
-        new_step_items.extend(apply_patch_results)
-        new_step_items.extend(local_shell_results)
-
         # Next, run the MCP approval requests
         if processed_response.mcp_approval_requests:
             approval_results = await cls.execute_mcp_approval_requests(
@@ -999,7 +1013,9 @@ async def run_single_tool(
                             # Not yet decided - need to interrupt for approval
                             from .items import ToolApprovalItem
 
-                            approval_item = ToolApprovalItem(agent=agent, raw_item=tool_call)
+                            approval_item = ToolApprovalItem(
+                                agent=agent, raw_item=tool_call, tool_name=func_tool.name
+                            )
                             return FunctionToolResult(
                                 tool=func_tool, output=None, run_item=approval_item
                             )
@@ -1800,16 +1816,75 @@ async def execute(
         context_wrapper: RunContextWrapper[TContext],
         config: RunConfig,
     ) -> RunItem:
+        shell_call = _coerce_shell_call(call.tool_call)
+        shell_tool = call.shell_tool
+
+        # Check if approval is needed
+        needs_approval_result: bool = False
+        if isinstance(shell_tool.needs_approval, bool):
+            needs_approval_result = shell_tool.needs_approval
+        elif callable(shell_tool.needs_approval):
+            maybe_awaitable = shell_tool.needs_approval(
+                context_wrapper, shell_call.action, shell_call.call_id
+            )
+            needs_approval_result = (
+                await maybe_awaitable if inspect.isawaitable(maybe_awaitable) else maybe_awaitable
+            )
+
+        if needs_approval_result:
+            # Create approval item with explicit tool name
+            approval_item = ToolApprovalItem(
+                agent=agent, raw_item=call.tool_call, tool_name=shell_tool.name
+            )
+
+            # Handle on_approval callback if provided
+            if shell_tool.on_approval:
+                maybe_awaitable_decision = shell_tool.on_approval(context_wrapper, approval_item)
+                decision = (
+                    await maybe_awaitable_decision
+                    if inspect.isawaitable(maybe_awaitable_decision)
+                    else maybe_awaitable_decision
+                )
+                if decision.get("approve") is True:
+                    context_wrapper.approve_tool(approval_item)
+                elif decision.get("approve") is False:
+                    context_wrapper.reject_tool(approval_item)
+
+            # Check approval status
+            approval_status = context_wrapper.is_tool_approved(shell_tool.name, shell_call.call_id)
+
+            if approval_status is False:
+                # Rejected - return rejection output
+                response = "Tool execution was not approved."
+                rejection_output: dict[str, Any] = {
+                    "stdout": "",
+                    "stderr": response,
+                    "outcome": {"type": "exit", "exitCode": None},
+                }
+                rejection_raw_item: dict[str, Any] = {
+                    "type": "shell_call_output",
+                    "call_id": shell_call.call_id,
+                    "output": [rejection_output],
+                }
+                return ToolCallOutputItem(
+                    agent=agent,
+                    output=response,
+                    raw_item=cast(Any, rejection_raw_item),
+                )
+
+            if approval_status is not True:
+                # Pending approval - return approval item
+                return approval_item
+
+        # Approved or no approval needed - proceed with execution
         await asyncio.gather(
-            hooks.on_tool_start(context_wrapper, agent, call.shell_tool),
+            hooks.on_tool_start(context_wrapper, agent, shell_tool),
             (
-                agent.hooks.on_tool_start(context_wrapper, agent, call.shell_tool)
+                agent.hooks.on_tool_start(context_wrapper, agent, shell_tool)
                 if agent.hooks
                 else _coro.noop_coroutine()
             ),
         )
-
-        shell_call = _coerce_shell_call(call.tool_call)
         request = ShellCommandRequest(ctx_wrapper=context_wrapper, data=shell_call)
         status: Literal["completed", "failed"] = "completed"
         output_text = ""
@@ -1924,6 +1999,65 @@ async def execute(
         config: RunConfig,
     ) -> RunItem:
         apply_patch_tool = call.apply_patch_tool
+        operation = _coerce_apply_patch_operation(call.tool_call)
+
+        # Extract call_id from tool_call
+        call_id = _extract_apply_patch_call_id(call.tool_call)
+
+        # Check if approval is needed
+        needs_approval_result: bool = False
+        if isinstance(apply_patch_tool.needs_approval, bool):
+            needs_approval_result = apply_patch_tool.needs_approval
+        elif callable(apply_patch_tool.needs_approval):
+            maybe_awaitable = apply_patch_tool.needs_approval(context_wrapper, operation, call_id)
+            needs_approval_result = (
+                await maybe_awaitable if inspect.isawaitable(maybe_awaitable) else maybe_awaitable
+            )
+
+        if needs_approval_result:
+            # Create approval item with explicit tool name
+            approval_item = ToolApprovalItem(
+                agent=agent, raw_item=call.tool_call, tool_name=apply_patch_tool.name
+            )
+
+            # Handle on_approval callback if provided
+            if apply_patch_tool.on_approval:
+                maybe_awaitable_decision = apply_patch_tool.on_approval(
+                    context_wrapper, approval_item
+                )
+                decision = (
+                    await maybe_awaitable_decision
+                    if inspect.isawaitable(maybe_awaitable_decision)
+                    else maybe_awaitable_decision
+                )
+                if decision.get("approve") is True:
+                    context_wrapper.approve_tool(approval_item)
+                elif decision.get("approve") is False:
+                    context_wrapper.reject_tool(approval_item)
+
+            # Check approval status
+            approval_status = context_wrapper.is_tool_approved(apply_patch_tool.name, call_id)
+
+            if approval_status is False:
+                # Rejected - return rejection output
+                response = "Tool execution was not approved."
+                rejection_raw_item: dict[str, Any] = {
+                    "type": "apply_patch_call_output",
+                    "call_id": call_id,
+                    "status": "failed",
+                    "output": response,
+                }
+                return ToolCallOutputItem(
+                    agent=agent,
+                    output=response,
+                    raw_item=cast(Any, rejection_raw_item),
+                )
+
+            if approval_status is not True:
+                # Pending approval - return approval item
+                return approval_item
+
+        # Approved or no approval needed - proceed with execution
         await asyncio.gather(
             hooks.on_tool_start(context_wrapper, agent, apply_patch_tool),
             (
@@ -1937,7 +2071,6 @@ async def execute(
         output_text = ""
 
         try:
-            operation = _coerce_apply_patch_operation(call.tool_call)
             editor = apply_patch_tool.editor
             if operation.type == "create_file":
                 result = editor.create_file(operation)

src/agents/items.py

@@ -327,20 +327,71 @@ class MCPApprovalResponseItem(RunItemBase[McpApprovalResponse]):
     type: Literal["mcp_approval_response_item"] = "mcp_approval_response_item"
 
 
+# Union type for tool approval raw items - supports function tools, hosted tools, shell tools, etc.
+ToolApprovalRawItem: TypeAlias = Union[
+    ResponseFunctionToolCall,
+    McpCall,
+    LocalShellCall,
+    dict[str, Any],  # For flexibility with other tool types
+]
+
+
 @dataclass
-class ToolApprovalItem(RunItemBase[ResponseFunctionToolCall]):
+class ToolApprovalItem(RunItemBase[Any]):
     """Represents a tool call that requires approval before execution.
 
     When a tool has `needs_approval=True`, the run will be interrupted and this item will be
     added to the interruptions list. You can then approve or reject the tool call using
     RunState.approve() or RunState.reject() and resume the run.
     """
 
-    raw_item: ResponseFunctionToolCall
-    """The raw function tool call that requires approval."""
+    raw_item: ToolApprovalRawItem
+    """The raw tool call that requires approval. Can be a function tool call, hosted tool call,
+    shell call, or other tool type.
+    """
+
+    tool_name: str | None = None
+    """Explicit tool name to use for approval tracking when not present on the raw item.
+    If not provided, falls back to raw_item.name.
+    """
 
     type: Literal["tool_approval_item"] = "tool_approval_item"
 
+    def __post_init__(self) -> None:
+        """Set tool_name from raw_item.name if not explicitly provided."""
+        if self.tool_name is None:
+            # Extract name from raw_item - handle different types
+            if isinstance(self.raw_item, dict):
+                self.tool_name = self.raw_item.get("name")
+            elif hasattr(self.raw_item, "name"):
+                self.tool_name = self.raw_item.name
+            else:
+                self.tool_name = None
+
+    @property
+    def name(self) -> str | None:
+        """Returns the tool name if available on the raw item or provided explicitly.
+
+        Kept for backwards compatibility with code that previously relied on raw_item.name.
+        """
+        return self.tool_name or (
+            getattr(self.raw_item, "name", None)
+            if not isinstance(self.raw_item, dict)
+            else self.raw_item.get("name")
+        )
+
+    @property
+    def arguments(self) -> str | None:
+        """Returns the arguments if the raw item has an arguments property, otherwise None.
+
+        This provides a safe way to access tool call arguments regardless of the raw_item type.
+        """
+        if isinstance(self.raw_item, dict):
+            return self.raw_item.get("arguments")
+        elif hasattr(self.raw_item, "arguments"):
+            return self.raw_item.arguments
+        return None
+
 
 RunItem: TypeAlias = Union[
     MessageOutputItem,