docs: add missing changes (#2526)

Author: seratch

docs/running_agents.md

@@ -62,9 +62,67 @@ The `run_config` parameter lets you configure some global settings for the agent
 -   [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Customize how new user input is merged with session history before each turn when using Sessions.
 -   [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: Hook to edit the fully prepared model input (instructions and input items) immediately before the model call, e.g., to trim history or inject a system prompt.
 -   [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: Customize the model-visible message when a tool call is rejected during approval flows.
+-   [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: Control whether reasoning item IDs are preserved or omitted when the runner converts prior outputs into next-turn model input.
 
 Nested handoffs are available as an opt-in beta. Enable the collapsed-transcript behavior by passing `RunConfig(nest_handoff_history=True)` or set `handoff(..., nest_handoff_history=True)` to turn it on for a specific handoff. If you prefer to keep the raw transcript (the default), leave the flag unset or provide a `handoff_input_filter` (or `handoff_history_mapper`) that forwards the conversation exactly as you need. To change the wrapper text used in the generated summary without writing a custom mapper, call [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] (and [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] to restore the defaults).
 
+### Run config details
+
+#### `tool_error_formatter`
+
+Use `tool_error_formatter` to customize the message that is returned to the model when a tool call is rejected in an approval flow.
+
+The formatter receives [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs] with:
+
+-   `kind`: The error category. Today this is `"approval_rejected"`.
+-   `tool_type`: The tool runtime (`"function"`, `"computer"`, `"shell"`, or `"apply_patch"`).
+-   `tool_name`: The tool name.
+-   `call_id`: The tool call ID.
+-   `default_message`: The SDK's default model-visible message.
+-   `run_context`: The active run context wrapper.
+
+Return a string to replace the message, or `None` to use the SDK default.
+
+```python
+from agents import Agent, RunConfig, Runner, ToolErrorFormatterArgs
+
+
+def format_rejection(args: ToolErrorFormatterArgs[None]) -> str | None:
+    if args.kind == "approval_rejected":
+        return (
+            f"Tool call '{args.tool_name}' was rejected by a human reviewer. "
+            "Ask for confirmation or propose a safer alternative."
+        )
+    return None
+
+
+agent = Agent(name="Assistant")
+result = Runner.run_sync(
+    agent,
+    "Please delete the production database.",
+    run_config=RunConfig(tool_error_formatter=format_rejection),
+)
+```
+
+#### `reasoning_item_id_policy`
+
+`reasoning_item_id_policy` controls how reasoning items are converted into next-turn model input when the runner carries history forward (for example, when using `RunResult.to_input_list()` or session-backed runs).
+
+-   `None` or `"preserve"` (default): Keep reasoning item IDs.
+-   `"omit"`: Strip reasoning item IDs from the generated next-turn input.
+
+Use `"omit"` primarily as an opt-in mitigation for a class of Responses API 400 errors where a reasoning item is sent with an `id` but without the required following item (for example, `Item 'rs_...' of type 'reasoning' was provided without its required following item.`).
+
+This can happen in multi-turn agent runs when the SDK constructs follow-up input from prior outputs (including session persistence, server-managed conversation deltas, streamed/non-streamed follow-up turns, and resume paths) and a reasoning item ID is preserved but the provider requires that ID to remain paired with its corresponding following item.
+
+Setting `reasoning_item_id_policy="omit"` keeps the reasoning content but strips the reasoning item `id`, which avoids triggering that API invariant in SDK-generated follow-up inputs.
+
+Scope notes:
+
+-   This only changes reasoning items generated/forwarded by the SDK when it builds follow-up input.
+-   It does not rewrite user-supplied initial input items.
+-   `call_model_input_filter` can still intentionally reintroduce reasoning IDs after this policy is applied.
+
 ## Conversations/chat threads
 
 Calling any of the run methods can result in one or more agents running (and hence one or more LLM calls), but it represents a single logical turn in a chat conversation. For example:
@@ -193,6 +251,16 @@ async def main():
         print(f"Assistant: {result.final_output}")
 ```
 
+!!! note
+
+    The SDK automatically retries `conversation_locked` errors with backoff. In server-managed
+    conversation runs, it rewinds the internal conversation-tracker input before retrying so the
+    same prepared items can be resent cleanly.
+
+    In local session-based runs (which cannot be combined with `conversation_id`,
+    `previous_response_id`, or `auto_previous_response_id`), the SDK also performs a best-effort
+    rollback of recently persisted input items to reduce duplicate history entries after a retry.
+
 ## Call model input filter
 
 Use `call_model_input_filter` to edit the model input right before the model call. The hook receives the current agent, context, and the combined input items (including session history when present) and returns a new `ModelInputData`.

docs/sessions/index.md

@@ -53,6 +53,67 @@ When session memory is enabled:
 
 This eliminates the need to manually call `.to_input_list()` and manage conversation state between runs.
 
+## Customizing prepared input
+
+When you pass a session, the runner normally prepares model input as:
+
+1. Session history (retrieved from `session.get_items(...)`)
+2. New turn input
+
+Use [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] to customize that merge step before the model call. The callback receives two lists:
+
+-   `history`: The retrieved session history (already normalized into input-item format)
+-   `new_input`: The current turn's new input items
+
+Return the final list of input items that should be sent to the model.
+
+```python
+from agents import Agent, RunConfig, Runner, SQLiteSession
+
+
+def keep_recent_history(history, new_input):
+    # Keep only the last 10 history items, then append the new turn.
+    return history[-10:] + new_input
+
+
+agent = Agent(name="Assistant")
+session = SQLiteSession("conversation_123")
+
+result = await Runner.run(
+    agent,
+    "Continue from the latest updates only.",
+    session=session,
+    run_config=RunConfig(session_input_callback=keep_recent_history),
+)
+```
+
+Use this when you need custom pruning, reordering, or selective inclusion of history without changing how the session stores items.
+
+## Limiting retrieved history
+
+Use [`SessionSettings`][agents.memory.SessionSettings] to control how much history is fetched before each run.
+
+-   `SessionSettings(limit=None)` (default): retrieve all available session items
+-   `SessionSettings(limit=N)`: retrieve only the most recent `N` items
+
+You can apply this per run via [`RunConfig.session_settings`][agents.run.RunConfig.session_settings]:
+
+```python
+from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession
+
+agent = Agent(name="Assistant")
+session = SQLiteSession("conversation_123")
+
+result = await Runner.run(
+    agent,
+    "Summarize our recent discussion.",
+    session=session,
+    run_config=RunConfig(session_settings=SessionSettings(limit=50)),
+)
+```
+
+If your session implementation exposes default session settings, `RunConfig.session_settings` overrides any non-`None` values for that run. This is useful for long conversations where you want to cap retrieval size without changing the session's default behavior.
+
 ## Memory operations
 
 ### Basic operations