Skip to content

Commit c688a19

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 c7afb17 commit c688a19

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
@@ -66,6 +66,33 @@ interface BedrockInferenceConfig {
6666
temperature?: number
6767
}
6868

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

@@ -620,6 +648,9 @@ export class AwsBedrockHandler extends BaseProvider implements SingleCompletionH
620648
system: formatted.system,
621649
inferenceConfig,
622650
...(additionalModelRequestFields && { additionalModelRequestFields }),
651+
...(baseModelId.includes("claude") && {
652+
additionalModelResponseFieldPaths: ANTHROPIC_RESPONSE_FIELD_PATHS,
653+
}),
623654
// Add anthropic_version at top level when using thinking features
624655
...(thinkingEnabled && { anthropic_version: "bedrock-2023-05-31" }),
625656
toolConfig,
@@ -872,9 +903,12 @@ export class AwsBedrockHandler extends BaseProvider implements SingleCompletionH
872903
if (streamEvent.messageStop) {
873904
outputLimitReached = streamEvent.messageStop.stopReason === "max_tokens"
874905
if (streamEvent.messageStop.stopReason) {
906+
const details = formatStopDetails(streamEvent.messageStop.additionalModelResponseFields)
875907
yield {
876908
type: "stop_reason",
877-
reason: streamEvent.messageStop.stopReason,
909+
reason: details
910+
? `${streamEvent.messageStop.stopReason} (${details})`
911+
: streamEvent.messageStop.stopReason,
878912
}
879913
}
880914
continue

0 commit comments

Comments
 (0)