Skip to content

Commit 1aae58d

Browse files
committed
feat(bedrock): forward Anthropic stop_details into the stop-reason diagnostics
Part of Zoo-Code-Org#1820: an Opus 5.5 turn ended with a bare "content_filtered" and no way to tell which classifier declined it. Anthropic returns a stop_details object naming the refusal category (for example reasoning_extraction) and a human-readable explanation. Bedrock only forwards model response fields that are requested by JSON Pointer, so ask for /stop_details on Claude models and append category and explanation to the stop_reason chunk, e.g. "content_filtered (reasoning_extraction: ...)". The explanation text is not stable, so it is shown, not parsed. Converse ignores a valid pointer the model does not return. Not yet effective: in a live test on 2026-09-26, Opus 5.5 on Bedrock accepted the request field but returned content_filtered turns without additionalModelResponseFields. Kept because it is harmless and starts working if Bedrock begins forwarding the field; the code comment says so. https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#what-a-refusal-looks-like https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html
1 parent 072e23c commit 1aae58d

2 files changed

Lines changed: 102 additions & 1 deletion

File tree

‎src/api/providers/__tests__/bedrock.stream-diagnostics.spec.ts‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ vi.mock("@aws-sdk/client-bedrock-runtime", () => ({
3737
}))
3838

3939
import type { Anthropic } from "@anthropic-ai/sdk"
40+
import { ConverseStreamCommand } from "@aws-sdk/client-bedrock-runtime"
4041

4142
import { AwsBedrockHandler, BEDROCK_STREAM_EXCEPTION_KEYS } from "../bedrock"
4243
import { OutputTokenLimitError } from "../utils/output-token-limit-error"
@@ -159,6 +160,72 @@ describe("AwsBedrockHandler stream diagnostics", () => {
159160
{ type: "stop_reason", reason: "end_turn" },
160161
])
161162
})
163+
164+
describe("stop_details forwarding", () => {
165+
it("asks Bedrock to forward Anthropic's stop_details for Claude models", async () => {
166+
const handler = createHandler([{ messageStop: { stopReason: "end_turn" } }])
167+
await collect(handler)
168+
169+
const payload = vi.mocked(ConverseStreamCommand).mock.calls[0][0]
170+
expect(payload.additionalModelResponseFieldPaths).toEqual(["/stop_details"])
171+
})
172+
173+
it("appends the refusal category and explanation to the stop reason", async () => {
174+
const chunks = await collect(
175+
createHandler([
176+
{
177+
messageStop: {
178+
stopReason: "content_filtered",
179+
additionalModelResponseFields: {
180+
stop_details: {
181+
type: "refusal",
182+
category: "reasoning_extraction",
183+
explanation: "Declined to reproduce internal reasoning.",
184+
},
185+
},
186+
},
187+
},
188+
]),
189+
)
190+
191+
expect(chunks).toContainEqual({
192+
type: "stop_reason",
193+
reason: "content_filtered (reasoning_extraction: Declined to reproduce internal reasoning.)",
194+
})
195+
})
196+
197+
it("falls back to the stop_details type when category and explanation are null", async () => {
198+
const chunks = await collect(
199+
createHandler([
200+
{
201+
messageStop: {
202+
stopReason: "content_filtered",
203+
additionalModelResponseFields: {
204+
stop_details: { type: "refusal", category: null, explanation: null },
205+
},
206+
},
207+
},
208+
]),
209+
)
210+
211+
expect(chunks).toContainEqual({ type: "stop_reason", reason: "content_filtered (refusal)" })
212+
})
213+
214+
it("keeps the bare stop reason when stop_details is null", async () => {
215+
const chunks = await collect(
216+
createHandler([
217+
{
218+
messageStop: {
219+
stopReason: "end_turn",
220+
additionalModelResponseFields: { stop_details: null },
221+
},
222+
},
223+
]),
224+
)
225+
226+
expect(chunks).toContainEqual({ type: "stop_reason", reason: "end_turn" })
227+
})
228+
})
162229
})
163230

164231
describe("raw API dump", () => {

‎src/api/providers/bedrock.ts‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,33 @@ interface BedrockInferenceConfig {
6868
temperature?: number
6969
}
7070

71+
/**
72+
* Asks Bedrock to forward Anthropic's `stop_details`, which names the classifier category behind a refusal
73+
* (for example `reasoning_extraction`). Bedrock reports such refusals only as `content_filtered` otherwise.
74+
* A valid pointer the model doesn't return is ignored by Converse. See #1820.
75+
*
76+
* Not yet effective: as of 2026-09-26, Opus 5.5 on Bedrock accepted this request field but returned
77+
* `content_filtered` turns without `additionalModelResponseFields`, so no category was available.
78+
* Kept because it is harmless and starts working if Bedrock begins forwarding the field.
79+
*
80+
* - https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#what-a-refusal-looks-like
81+
* - https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html#bedrock-runtime_ConverseStream-request-additionalModelResponseFieldPaths
82+
*/
83+
const ANTHROPIC_RESPONSE_FIELD_PATHS = ["/stop_details"]
84+
85+
/** Renders forwarded `stop_details` as `category: explanation`; the explanation text is unstable, so it's shown, not parsed. */
86+
export function formatStopDetails(fields: Record<string, unknown> | undefined): string | undefined {
87+
const details = fields?.stop_details
88+
if (!details || typeof details !== "object") {
89+
return undefined
90+
}
91+
const { type, category, explanation } = details as Record<string, unknown>
92+
const parts = [category ?? type, explanation].filter(
93+
(part): part is string => typeof part === "string" && part.length > 0,
94+
)
95+
return parts.length > 0 ? parts.join(": ") : undefined
96+
}
97+
7198
/**
7299
* Models that write short user-facing progress updates between tool calls
73100
* ("what I found, what I'm doing next") as separate `thinking` blocks rather than `text` blocks.
@@ -119,6 +146,7 @@ interface BedrockPayload {
119146
inferenceConfig: BedrockInferenceConfig
120147
anthropic_version?: string
121148
additionalModelRequestFields?: BedrockAdditionalModelFields
149+
additionalModelResponseFieldPaths?: string[]
122150
toolConfig?: ToolConfiguration
123151
}
124152

@@ -622,6 +650,9 @@ export class AwsBedrockHandler extends BaseProvider implements SingleCompletionH
622650
system: formatted.system,
623651
inferenceConfig,
624652
...(additionalModelRequestFields && { additionalModelRequestFields }),
653+
...(baseModelId.includes("claude") && {
654+
additionalModelResponseFieldPaths: ANTHROPIC_RESPONSE_FIELD_PATHS,
655+
}),
625656
// Add anthropic_version at top level when using thinking features
626657
...(thinkingEnabled && { anthropic_version: "bedrock-2023-05-31" }),
627658
toolConfig,
@@ -874,9 +905,12 @@ export class AwsBedrockHandler extends BaseProvider implements SingleCompletionH
874905
if (streamEvent.messageStop) {
875906
outputLimitReached = streamEvent.messageStop.stopReason === "max_tokens"
876907
if (streamEvent.messageStop.stopReason) {
908+
const details = formatStopDetails(streamEvent.messageStop.additionalModelResponseFields)
877909
yield {
878910
type: "stop_reason",
879-
reason: streamEvent.messageStop.stopReason,
911+
reason: details
912+
? `${streamEvent.messageStop.stopReason} (${details})`
913+
: streamEvent.messageStop.stopReason,
880914
}
881915
}
882916
continue

0 commit comments

Comments
 (0)