feat: #2658 preserve explicit approval rejection messages across resume flows (#2660)

Author: seratch

examples/agent_patterns/human_in_the_loop_custom_rejection.py

@@ -3,8 +3,9 @@
 This example is intentionally minimal:
 1. A single sensitive tool requires human approval.
 2. The first turn always issues that tool call.
-3. Rejection uses a custom message via ``tool_error_formatter``.
-4. The example prints both the formatter output and the assistant's final reply.
+3. ``tool_error_formatter`` defines the universal fallback message shape.
+4. A per-call ``rejection_message`` passed to ``state.reject(...)`` overrides that fallback.
+5. The example prints both the tool output and the assistant's final reply.
 """
 
 import asyncio
@@ -21,7 +22,7 @@
 
 
 async def tool_error_formatter(args: ToolErrorFormatterArgs[None]) -> str | None:
-    """Build a simple output message for rejected tool calls."""
+    """Build the universal fallback output message for rejected tool calls."""
     if args.kind != "approval_rejected":
         return None
     # The default message is "Tool execution was not approved."
@@ -60,6 +61,8 @@ async def main() -> None:
         tools=[publish_announcement],
     )
     run_config = RunConfig(tool_error_formatter=tool_error_formatter)
+    # ``tool_error_formatter`` is the universal fallback for approval rejects.
+    # A specific ``rejection_message`` passed to ``state.reject(...)`` below overrides it.
 
     result = await Runner.run(
         agent,
@@ -81,7 +84,13 @@ async def main() -> None:
             if approved:
                 state.approve(interruption)
             else:
-                state.reject(interruption)
+                # This per-call rejection message takes precedence over ``tool_error_formatter``.
+                state.reject(
+                    interruption,
+                    rejection_message=(
+                        "Publish action was canceled because the reviewer denied approval."
+                    ),
+                )
 
         result = await Runner.run(agent, state, run_config=run_config)
 

src/agents/realtime/session.py

@@ -10,6 +10,7 @@
 from pydantic import BaseModel
 from typing_extensions import assert_never
 
+from .._tool_identity import get_function_tool_lookup_key_for_tool
 from ..agent import Agent
 from ..exceptions import UserError
 from ..handoffs import Handoff
@@ -527,6 +528,14 @@ async def _send_tool_rejection(
 
     async def _resolve_approval_rejection_message(self, *, tool: FunctionTool, call_id: str) -> str:
         """Resolve model-visible output text for approval rejections."""
+        explicit_message = self._context_wrapper.get_rejection_message(
+            tool.name,
+            call_id,
+            tool_lookup_key=get_function_tool_lookup_key_for_tool(tool),
+        )
+        if explicit_message is not None:
+            return explicit_message
+
         formatter = self._run_config.get("tool_error_formatter")
         if formatter is None:
             return REJECTION_MESSAGE
@@ -574,14 +583,24 @@ async def approve_tool_call(self, call_id: str, *, always: bool = False) -> None
         else:
             await self._handle_tool_call(tool_call, agent_snapshot=agent_snapshot)
 
-    async def reject_tool_call(self, call_id: str, *, always: bool = False) -> None:
+    async def reject_tool_call(
+        self,
+        call_id: str,
+        *,
+        always: bool = False,
+        rejection_message: str | None = None,
+    ) -> None:
         """Reject a pending tool call and notify the model."""
         pending = self._pending_tool_calls.pop(call_id, None)
         if pending is None:
             return
 
         tool_call, agent_snapshot, function_tool, approval_item = pending
-        self._context_wrapper.reject_tool(approval_item, always_reject=always)
+        self._context_wrapper.reject_tool(
+            approval_item,
+            always_reject=always,
+            rejection_message=rejection_message,
+        )
         await self._send_tool_rejection(tool_call, tool=function_tool, agent=agent_snapshot)
 
     async def _handle_tool_call(

src/agents/run_context.py

@@ -35,6 +35,8 @@ class _ApprovalRecord:
 
     approved: bool | list[str] = field(default_factory=list)
     rejected: bool | list[str] = field(default_factory=list)
+    rejection_messages: dict[str, str] = field(default_factory=dict)
+    sticky_rejection_message: str | None = None
 
 
 @dataclass(eq=False)
@@ -207,8 +209,101 @@ def _get_approval_status_for_key(self, approval_key: str, call_id: str) -> bool
         # Per-call approvals are scoped to the exact call ID, so other calls require a new decision.
         return None
 
+    @staticmethod
+    def _clear_rejection_message(record: _ApprovalRecord, call_id: str | None) -> None:
+        if call_id is None:
+            return
+        record.rejection_messages.pop(call_id, None)
+
+    @staticmethod
+    def _get_rejection_message_for_key(record: _ApprovalRecord, call_id: str) -> str | None:
+        if record.rejected is True:
+            if call_id in record.rejection_messages:
+                return record.rejection_messages[call_id]
+            return record.sticky_rejection_message
+        if isinstance(record.rejected, list) and call_id in record.rejected:
+            return record.rejection_messages.get(call_id)
+        return None
+
+    def get_rejection_message(
+        self,
+        tool_name: str,
+        call_id: str,
+        *,
+        tool_namespace: str | None = None,
+        existing_pending: ToolApprovalItem | None = None,
+        tool_lookup_key: FunctionToolLookupKey | None = None,
+    ) -> str | None:
+        """Return a stored rejection message for a tool call if one exists."""
+        candidates: list[str] = []
+        explicit_namespace = (
+            tool_namespace if isinstance(tool_namespace, str) and tool_namespace else None
+        )
+        pending_namespace = (
+            self._resolve_tool_namespace(existing_pending) if existing_pending is not None else None
+        )
+        pending_key = self._resolve_approval_key(existing_pending) if existing_pending else None
+        pending_tool_name = self._resolve_tool_name(existing_pending) if existing_pending else None
+        pending_keys = (
+            list(self._resolve_approval_keys(existing_pending))
+            if existing_pending is not None
+            else []
+        )
+
+        if existing_pending and pending_key is not None:
+            candidates.append(pending_key)
+        explicit_keys = (
+            list(
+                get_function_tool_approval_keys(
+                    tool_name=tool_name,
+                    tool_namespace=explicit_namespace,
+                    tool_lookup_key=tool_lookup_key,
+                    include_legacy_deferred_key=True,
+                )
+            )
+            if explicit_namespace is not None or tool_lookup_key is not None
+            else []
+        )
+        for explicit_key in explicit_keys:
+            if explicit_key not in candidates:
+                candidates.append(explicit_key)
+        if not explicit_keys and pending_namespace and pending_key is not None:
+            if pending_key not in candidates:
+                candidates.append(pending_key)
+        if (
+            explicit_namespace is None
+            and tool_lookup_key is None
+            and existing_pending is None
+            and tool_name not in candidates
+        ):
+            candidates.append(tool_name)
+        if existing_pending:
+            for pending_candidate in pending_keys:
+                if pending_candidate not in candidates:
+                    candidates.append(pending_candidate)
+            if (
+                pending_namespace is None
+                and pending_tool_name is not None
+                and pending_tool_name not in candidates
+            ):
+                candidates.append(pending_tool_name)
+
+        for candidate in candidates:
+            approval_entry = self._approvals.get(candidate)
+            if not approval_entry:
+                continue
+            message = self._get_rejection_message_for_key(approval_entry, call_id)
+            if message is not None:
+                return message
+        return None
+
     def _apply_approval_decision(
-        self, approval_item: ToolApprovalItem, *, always: bool, approve: bool
+        self,
+        approval_item: ToolApprovalItem,
+        *,
+        always: bool,
+        approve: bool,
+        rejection_message: str | None = None,
     ) -> None:
         """Record an approval or rejection decision."""
         approval_keys = self._resolve_approval_keys(approval_item) or ("unknown_tool",)
@@ -223,6 +318,14 @@ def _apply_approval_decision(
                 approval_entry.rejected = [] if approve else True
                 if not approve:
                     approval_entry.approved = False
+                    if rejection_message is not None and call_id is not None:
+                        approval_entry.rejection_messages[call_id] = rejection_message
+                    elif call_id is not None:
+                        self._clear_rejection_message(approval_entry, call_id)
+                    approval_entry.sticky_rejection_message = rejection_message
+                else:
+                    approval_entry.rejection_messages.clear()
+                    approval_entry.sticky_rejection_message = None
                 continue
 
             opposite = approval_entry.rejected if approve else approval_entry.approved
@@ -232,6 +335,13 @@ def _apply_approval_decision(
             target = approval_entry.approved if approve else approval_entry.rejected
             if isinstance(target, list) and call_id not in target:
                 target.append(call_id)
+            if approve:
+                self._clear_rejection_message(approval_entry, call_id)
+            elif call_id is not None:
+                if rejection_message is not None:
+                    approval_entry.rejection_messages[call_id] = rejection_message
+                else:
+                    self._clear_rejection_message(approval_entry, call_id)
 
     def approve_tool(self, approval_item: ToolApprovalItem, always_approve: bool = False) -> None:
         """Approve a tool call, optionally for all future calls."""
@@ -241,12 +351,18 @@ def approve_tool(self, approval_item: ToolApprovalItem, always_approve: bool = F
             approve=True,
         )
 
-    def reject_tool(self, approval_item: ToolApprovalItem, always_reject: bool = False) -> None:
+    def reject_tool(
+        self,
+        approval_item: ToolApprovalItem,
+        always_reject: bool = False,
+        rejection_message: str | None = None,
+    ) -> None:
         """Reject a tool call, optionally for all future calls."""
         self._apply_approval_decision(
             approval_item,
             always=always_reject,
             approve=False,
+            rejection_message=rejection_message,
         )
 
     def get_approval_status(
@@ -326,6 +442,16 @@ def _rebuild_approvals(self, approvals: dict[str, dict[str, Any]]) -> None:
             record = _ApprovalRecord()
             record.approved = record_dict.get("approved", [])
             record.rejected = record_dict.get("rejected", [])
+            rejection_messages = record_dict.get("rejection_messages", {})
+            if isinstance(rejection_messages, dict):
+                record.rejection_messages = {
+                    str(call_id): message
+                    for call_id, message in rejection_messages.items()
+                    if isinstance(message, str)
+                }
+            sticky_rejection_message = record_dict.get("sticky_rejection_message")
+            if isinstance(sticky_rejection_message, str):
+                record.sticky_rejection_message = sticky_rejection_message
             self._approvals[tool_name] = record
 
     def _fork_with_tool_input(self, tool_input: Any) -> RunContextWrapper[TContext]:

src/agents/run_internal/tool_execution.py

@@ -1049,8 +1049,21 @@ async def resolve_approval_rejection_message(
     tool_type: Literal["function", "computer", "shell", "apply_patch"],
     tool_name: str,
     call_id: str,
+    tool_namespace: str | None = None,
+    tool_lookup_key: FunctionToolLookupKey | None = None,
+    existing_pending: ToolApprovalItem | None = None,
 ) -> str:
     """Resolve model-visible output text for approval rejections."""
+    explicit_message = context_wrapper.get_rejection_message(
+        tool_name,
+        call_id,
+        tool_namespace=tool_namespace,
+        tool_lookup_key=tool_lookup_key,
+        existing_pending=existing_pending,
+    )
+    if explicit_message is not None:
+        return explicit_message
+
     formatter = run_config.tool_error_formatter
     if formatter is None:
         return REJECTION_MESSAGE
@@ -1150,6 +1163,13 @@ def process_hosted_mcp_approvals(
                 "approval_request_id": request_id,
                 "approve": approved,
             }
+            rejection_message = context_wrapper.get_rejection_message(
+                tool_name=tool_name,
+                call_id=request_id,
+                existing_pending=approval_item,
+            )
+            if approved is False and rejection_message is not None:
+                raw_item["reason"] = rejection_message
             response_item = MCPApprovalResponseItem(raw_item=raw_item, agent=agent)
             append_item(response_item)
             continue
@@ -1199,6 +1219,13 @@ def collect_manual_mcp_approvals(
                 "approval_request_id": request_id,
                 "approve": approval_status,
             }
+            rejection_message = context_wrapper.get_rejection_message(
+                tool_name,
+                request_id,
+                existing_pending=existing_pending,
+            )
+            if approval_status is False and rejection_message is not None:
+                approval_response_raw["reason"] = rejection_message
             approved.append(MCPApprovalResponseItem(raw_item=approval_response_raw, agent=agent))
             continue
 
@@ -1520,6 +1547,8 @@ async def _maybe_execute_tool_approval(
             tool_type="function",
             tool_name=tool_trace_name(func_tool.name, tool_namespace) or func_tool.name,
             call_id=tool_call.call_id,
+            tool_namespace=tool_namespace,
+            tool_lookup_key=tool_lookup_key,
         )
         span_fn.set_error(
             SpanError(
@@ -1988,6 +2017,9 @@ async def _resolve_tool_run(
                     tool_type="function",
                     tool_name=display_tool_name,
                     call_id=call_id,
+                    tool_namespace=tool_namespace,
+                    tool_lookup_key=tool_lookup_key,
+                    existing_pending=interruption,
                 )
             _append_error(
                 message=message,

src/agents/run_internal/turn_resolution.py

@@ -32,6 +32,7 @@
     build_function_tool_lookup_map,
     get_function_tool_lookup_key,
     get_function_tool_lookup_key_for_call,
+    get_function_tool_lookup_key_for_tool,
     get_tool_call_namespace,
     get_tool_call_qualified_name,
     get_tool_call_trace_name,
@@ -705,12 +706,16 @@ async def _record_function_rejection(
             return
         rejection_message = REJECTION_MESSAGE
         if call_id:
+            tool_namespace = get_tool_call_namespace(tool_call)
             rejection_message = await resolve_approval_rejection_message(
                 context_wrapper=context_wrapper,
                 run_config=run_config,
                 tool_type="function",
                 tool_name=get_tool_call_trace_name(tool_call) or function_tool.name,
                 call_id=call_id,
+                tool_namespace=tool_namespace,
+                tool_lookup_key=get_function_tool_lookup_key_for_tool(function_tool),
+                existing_pending=approval_items_by_call_id.get(call_id),
             )
         rejected_function_outputs.append(
             function_rejection_item(