Release 0.15.0

[github-actions]

Release readiness review (v0.14.8 -> TARGET aa97486)

This is a release readiness report done by $final-release-review skill.

Diff

v0.14.8...aa97486

Release call:

🟢 GREEN LIGHT TO SHIP No release-blocking regressions were identified; the main user-facing behavior change is intentional, documented, tested, and paired with a minor version bump to 0.15.0.

Scope summary:

• 20 files changed (+243/-27); key areas touched: model refusal handling in src/agents/run_internal/, public exception/export surface in src/agents/, refusal/error-handler tests, docs for error_handlers, version metadata, and GitHub workflow action pins.

Risk assessment (ordered by impact):

1. Model refusals now surface as ModelRefusalError

   • Risk: 🟡 MODERATE. Existing callers that previously received a plaintext/empty final output for refusal messages may now see an exception unless they configure error_handlers["model_refusal"].
   • Evidence: Commit 2d40c09c adds ModelRefusalError, ItemHelpers.extract_refusal, refusal resolution in execute_tools_and_side_effects, and changes test_plaintext_agent_hosted_shell_with_refusal_message_is_final_output into an exception expectation.
   • Files: src/agents/exceptions.py, src/agents/items.py, src/agents/run_internal/turn_resolution.py, src/agents/run_error_handlers.py, tests/test_max_turns.py, tests/test_run_step_execution.py, docs/running_agents.md
   • Action: Run uv run pytest tests/test_max_turns.py tests/test_run_step_execution.py tests/test_responses.py -k "refusal or error_handler" and confirm refusal paths either raise ModelRefusalError or return configured fallback output as expected.

2. Streaming refusal fallback path has positive coverage, but unhandled streaming refusal should be validated

   • Risk: 🟢 LOW. The diff passes error_handlers into streamed turn resolution and tests handled streamed refusals, but an explicit no-handler streaming refusal regression test would reduce release risk.
   • Evidence: run_single_turn_streamed now accepts and forwards error_handlers; test_streamed_refusal_handler_returns_output covers the handled path, while the no-handler streamed refusal path is not directly covered in the changed tests.
   • Files: src/agents/run_internal/run_loop.py, src/agents/run_internal/turn_resolution.py, tests/test_max_turns.py
   • Action: Add or run a focused streamed no-handler refusal check and pass criteria: Runner.run_streamed(...).stream_events() propagates ModelRefusalError and terminates cleanly without hanging.

3. Runner API docstrings still mention only max_turns for error_handlers

   • Risk: 🟢 LOW. Runtime behavior and user docs are updated, but inline API documentation can mislead users discovering the feature through generated reference docs or IDE help.
   • Evidence: docs/running_agents.md documents "max_turns" and "model_refusal", but src/agents/run.py argument docs still say error_handlers: Error handlers keyed by error kind. Currently supports max_turns.
   • Files: src/agents/run.py, docs/running_agents.md
   • Action: Update the three Runner entry point docstrings to mention both "max_turns" and "model_refusal" before release docs are generated.

4. GitHub workflow action bumps affect release automation, not runtime package behavior

   • Risk: 🟢 LOW. Workflow pins for publishing, Codex automation, GitHub Script, and docs PR creation changed; no package code path depends on them.
   • Evidence: .github/workflows/publish.yml, release-review workflows, PR labeling, and docs update workflows changed action SHAs; pyproject.toml and uv.lock only bump package version to 0.15.0.
   • Files: .github/workflows/publish.yml, .github/workflows/release-pr.yml, .github/workflows/release-pr-update.yml, .github/workflows/pr-labels.yml, .github/workflows/update-docs.yml
   • Action: Confirm the release workflow dry run or next CI workflow execution reaches the build/publish step with the pinned action versions.

Notes:

• BASE_TAG was determined from local tags only with git tag -l 'v*' --sort=-v:refname | head -n1: v0.14.8.
• TARGET was determined with git rev-parse HEAD: aa97486e6e5b3ec69e61da36bf4238fe8c52fde2.
• Working tree status was clean.
• git diff --check v0.14.8...aa97486e6e5b3ec69e61da36bf4238fe8c52fde2 produced no whitespace/error output.
• Full local verification was not run in this review; assume CI runs the mandatory verification stack for the release candidate.