Python: mark hosted /responses incomplete on content_filter and length finish reasons

[Anish Mehta (anishmehta24)]

Motivation & Context

When an Azure OpenAI content filter stops a turn, the underlying chat completion carries finish_reason: "content_filter", but the hosted agent's /responses output reports a fully successful turn: HTTP 200, status: "completed", error: null, and the canned refusal delivered as ordinary output_text. An HTTP caller has no way to tell a filtered turn from a normal one short of matching the refusal string, which breaks on wording changes and localisation. The same applies to a turn cut off by the token limit (finish_reason: "length").

Root cause: _handle_inner_agent and _handle_inner_workflow in python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py iterate update.contents and never read update.finish_reason, so _handle_response always ends with emit_completed() unless an OAuth consent request was surfaced.

Description & Review Guide

• Major changes: _OutputItemTracker gains record_finish_reason(finish_reason) and an incomplete_reason property. Both update loops call record_finish_reason(update.finish_reason) before handling the update's contents. _handle_response now emits response.incomplete with incomplete_details.reason when a truncating finish reason was seen, using the ResponseIncompleteReason enum the AgentServer SDK already defines (content_filter, max_output_tokens), so the payload matches the OpenAI Responses shape the issue asks for. Only content_filter and length are mapped; stop/tool_calls leave the response completed as before.
• Impact: a filtered or length-limited turn now ends status: "incomplete" with incomplete_details: {"reason": ...} in both streaming (response.incomplete terminal event) and non-streaming bodies. The output items themselves are unchanged: the refusal text is still delivered so a caller can show it if it wants to. The existing OAuth consent emit_incomplete() behaviour is preserved (reason stays None in that case unless a filter also fired). The signal is sticky within a turn: a filter mid-way through a multi-step turn is not erased by a later update that finishes with stop, and content_filter wins over length if both are seen, since it is the more actionable signal.
• Focus for reviewers: the three-line terminal branch in _handle_response, and whether you want length mapped too (it is the other member of ResponseIncompleteReason, so it felt wrong to leave it out; happy to drop it if you'd rather keep this strictly to the reported case). Tests: new TestIncompleteFinishReasonSurfacing class next to the OAuth consent tests covers non-streaming and streaming content_filter, the length mapping, normal finish reasons still completing, stickiness across later updates, precedence, and the WorkflowAgent path via _build_text_workflow_agent(..., finish_reason=...).

Prepared with AI assistance (Claude Code) and human-verified: 6 of the 7 new tests fail on main and all pass with the fix; poe fmt, poe lint, poe pyright -P foundry_hosting, poe mypy -P foundry_hosting and the foundry_hosting test suite (324 passed, 28 skipped, 8 xfailed) were run locally.

Related Issue

Fixes #8475

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue
• This is not a breaking change.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Persist the incomplete-reason marker across workflow checkpoint recovery so filtered turns cannot be reported as completed.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Updates hosted Python /responses handling to report content_filter and length finishes as incomplete responses.

Changes:

• Tracks truncating finish reasons for agent and workflow streams.
• Emits incomplete metadata for streaming and non-streaming responses.
• Adds regression tests for finish-reason behavior.

File summaries

File	Summary
python/packages/foundry_hosting/tests/test_responses.py	Adds coverage for filtering, length limits, streaming, and workflow handling.
python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py	Tracks finish reasons and emits incomplete responses.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Lite (auto)

Note

Copilot is running an experiment and ran this review at Lite.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Anish Mehta (anishmehta24)]

Rebased on main to resolve the conflict with #8372 (request-scoped agent factories): the workflow loop now reads the workflow name from the request-scoped agent, and _SignalledIterator._drive keeps main's finally that closes the wrapped stream while still stamping each item. No functional change; fmt/lint/pyright/mypy and the package tests (341 passed) are green locally.

[Eduard van Valkenburg (eavanvalkenburg)]

Anish Mehta (@anishmehta24), the outstanding review concerns are addressed on the current head, and the full diff looks good to me.