RunContextWrapper in src/agents/run_context.py wraps user-supplied context and accumulates token usage, approval state, and tool invocation metadata across an agent run—it never reaches the LLM itself, serving only to thread dependencies and data to tools and callbacks. Run contexts support resumable checkpoints by deep-copying usage and approval state, while sharing approval decisions across related runs via _share_tool_state_with() to maintain consistent tool authorization.
RunContextWrapper in src/agents/run_context.py wraps the context object passed to Runner.run() and accumulates per-run usage, approval state, and tool invocation tracking. Contexts are not passed to the LLM — they exist solely to carry dependencies and data to tool functions, callbacks, and hooks.[1] TContext in src/agents/run_context.py is a TypeVar with a default of Any, making RunContextWrapper generic over the user-supplied context type.[1]
RunContextWrapper.usage (a Usage instance) accumulates token usage over the lifetime of an agent run. For streamed responses, its value is stale until the last chunk of the stream is processed.[1] RunContextWrapper.tool_input holds structured input for the current agent tool run when available, and is None otherwise.[1]
_ApprovalRecord in src/agents/run_context.py tracks per-tool approval and rejection state. approved and rejected are either booleans (permanent allow/deny) or lists of call IDs when approval is scoped to specific tool calls.[1] _ToolInvocationRecord in src/agents/run_context.py tracks the canonical identity and lifecycle of a single provider tool call ID, including its invocation_type, approval_scope, fingerprint, and boolean flags executed and completed.[1] RunContextWrapper._resolve_approval_key() derives a single canonical approval key for a ToolApprovalItem, preferring the key from get_function_tool_approval_keys and falling back to tool_qualified_name or the bare tool name.[1] RunContextWrapper._resolve_call_id() resolves the provider call ID from a ToolApprovalItem. For hosted MCP approval requests it uses the request_id; for mcp_approval_request items it checks provider_data.id; for regular function calls it reads call_id from the raw item.[1]
RunContextWrapper._copy_for_run_state() in src/agents/run_context.py deep-copies usage, _approvals, and _tool_invocations so that resumable checkpoints do not bleed token counts or approval state into each other.[1] RunContextWrapper._copy_for_run_state() also calls set_agent_tool_state_scope with a fresh UUID hex to give the copied context an independent tool-state scope.[1] RunContextWrapper._share_tool_state_with() wires _approvals, _tool_invocations, _allow_legacy_approval_binding_reconstruction, and _restored_unbound_approval_call_ids from the source context directly into the target, so both wrappers share the same mutable approval objects.[1]
Runtime annotations for ToolApprovalItem and TResponseInputItem in src/agents/run_context.py are resolved to Any at runtime (instead of importing items.py) to avoid circular imports. The TYPE_CHECKING guard keeps them typed for static analysis only.[1]
Sources