Summary

• document the supported call_model_input_filter pattern for injecting queued user/application input between tool turns
• clarify the boundaries: the filter changes the next model payload, but does not mutate RunResult.input, auto-persist injected items to a client-managed session, or pause the run
• add non-streamed and streamed characterization tests showing queued context messages injected after a tool call and before the next model turn

This follows the maintainer guidance on #2671 that RunConfig.call_model_input_filter is the existing supported hook for history compaction and queued external-message injection between tool turns, without adding a new turn hook/interceptor API.

Test plan

• make format
• uv run pytest tests/test_call_model_input_filter.py -q
• uv run mypy tests/test_call_model_input_filter.py
• uv run pyright tests/test_call_model_input_filter.py --project pyrightconfig.json
• uv run mkdocs build
• Second-agent review: claude -p on /tmp/oss-pr-second-agent-review.diff returned CLEAN with no blocking findings after the doc-example nit was fixed.

Full-suite note: I also ran the repo's $code-change-verification flow. make lint passed, but the full make tests/make typecheck gates are currently noisy in this local Python 3.14 environment due to unrelated optional-dependency and existing sandbox/voice/model failures outside this diff. The focused tests and file-level type checks above pass.

Issue number

Related to #2671

Checks

• I've added new tests (if relevant)
• I've added/updated the relevant documentation
• I've run make lint and make format
• I've made sure tests pass