Managed Agents event stream doesn't surface model refusal stop_reason / stop_details

[jpsorensen-asimov]

Summary

On the Messages API, a safety refusal is reported via stop_reason="refusal" plus
stop_details (RefusalStopDetails, with category = bio | cyber). The Managed
Agents session event stream appears to have no equivalent, so a consumer can't tell
that a turn ended due to a model refusal (or which category).

Details

Verified against main and the latest release (v0.107.1):

• BetaManagedAgentsSessionStatusIdleEvent.stop_reason is a union of only
  BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted — no refusal variant.
  (src/anthropic/types/beta/sessions/beta_managed_agents_session_status_idle_event.py)

• BetaManagedAgentsSpanModelRequestEndEvent exposes is_error and model_usage
  but no stop_reason / stop_details.
  (src/anthropic/types/beta/sessions/beta_managed_agents_span_model_request_end_event.py)

For comparison, the Messages API Message carries stop_reason (includes "refusal")
and stop_details (RefusalStopDetails). The BetaStopReason enum also lists
"refusal", but the session-idle event's stop_reason union does not include it.

Initial analysis — needs confirmation

A prompt that triggers a refusal on the Messages API appears, in a Managed Agents
session, to produce a turn with little/no text after which the session goes idle,
with no event field indicating a refusal occurred.

Possible resolution: include a refusal variant in the session.status_idle
stop_reason union, and/or surface the underlying model stop_reason / stop_details
on span.model_request_end.

[tsushanth]

Confirming and extending — the gap is wider than the two files you cited.
Verified against main at ebb1715 (v0.109.2) and anthropic-sdk-typescript@0.104.2.

Confirmation of the original analysis

• beta_managed_agents_session_status_idle_event.py:14-22 — StopReason is the 3-variant Union as described. No refusal.
• beta_managed_agents_span_model_request_end_event.py:14-30 — is_error: Optional[bool] only. No stop_reason / stop_details.

Five points the analysis didn't cover

1. The enum already knows about refusal — only the session Union doesn't

beta_stop_reason.py:7-15 — BetaStopReason Literal includes "refusal" alongside the other 7 reasons. So the spec acknowledges the variant; it just isn't plumbed into the managed-agents event surface. Internal inconsistency rather than a missing concept.

2. There's a financial cost to losing the refusal info, not just a UX cost

beta_refusal_stop_details.py carries fallback_credit_token:

Opaque code that refunds the cache-miss cost when retrying this refused request on the fallback model. […] Expires 5 minutes after the refusal.

When a Managed Agents refusal gets squashed at the session boundary, that token is unrecoverable. Callers who want the refund have no way to surface the token from the session event stream — it's a real-money side effect of the type gap, not only a missing label.

3. The sibling thread event has the same Union

beta_managed_agents_session_thread_status_idle_event.py:14-22 — same 3-variant Union. A refusal inside a child thread would be just as invisible. Any fix to session.status_idle should land on session.thread_status_idle too.

4. session.status_terminated carries no context at all

beta_managed_agents_session_status_terminated_event.py is id + processed_at + type only. If a refusal terminates a session outright (rather than yielding it idle), consumers get zero diagnostic information. Adjacent gap; worth raising on the same thread if you're auditing terminal events.

5. session.error.error Union has eight variants — none is refusal

beta_managed_agents_session_error_event.py — the Error Union is Unknown | ModelOverloaded | ModelRateLimited | ModelRequestFailed | MCPConnectionFailed | MCPAuthenticationFailed | Billing | CredentialHostUnreachable. So refusal can't currently surface as an error either, even if a maintainer wanted to treat it as one.

Cross-SDK: anthropic-sdk-typescript has the same gap

anthropic-sdk-typescript/src/resources/beta/sessions/events.ts — BetaManagedAgentsSessionStatusIdleEvent.stop_reason is the same Union of 3 members, and the file contains zero refusal references. Both file headers say "File generated from our OpenAPI spec by Stainless" — so whichever shape lands here will need to land in the OpenAPI spec, and both SDKs will regen from it.

Possible fix shapes (not recommending one — they're tradeoffs for the maintainers to weigh)

A. Refusal variant on the idle Union. Add a new BetaManagedAgentsSessionRefusal (with category, explanation, fallback_credit_token, etc.) to the StopReason Union on both session.status_idle and session.thread_status_idle. Smallest delta, preserves the Union shape.

B. Mirror the Messages API at the request span. Add stop_reason: BetaStopReason | null and stop_details: RefusalStopDetails | null to BetaManagedAgentsSpanModelRequestEndEvent. Matches the way Messages API exposes the same info via Message.stop_reason / Message.stop_details. Surfaces refusal at per-request granularity.

C. Both A and B. Would make the session event stream a strict superset of the Messages API metadata — terminal info at idle, per-request info at the span.

D. Refusal as an error variant. Adding BetaManagedAgentsRefusal to SessionErrorEvent.error. Mentioned only for completeness — mixing a legitimate stop_reason with errors may not be the contract you want.

Happy to help dig further on any of these. The fallback_credit_token angle is the one I'd be most curious about — once the session-event-stream consumer can see a refusal, what's the recommended pattern for redeeming the credit?