feat(AnthropicProvider): forced tool-use for schema-enforced structured output

Anthropic doesn't have an OpenAI-style response_format with json_schema.
The equivalent is forced tool-use: declare a single tool whose
input_schema matches the desired output shape, then force tool_choice
to that tool. The model returns a tool_use block whose input is
JSON-validated against the schema by Anthropic's own enforcement.

Two changes in AnthropicProvider:

1) Request build (buildRequestPayload): when responseFormat carries
   _agentosUseToolForStructuredOutput: true plus a tool: { name,
   input_schema }, prepend that tool to payload.tools and force
   tool_choice: { type: 'tool', name }. Caller-provided tools survive
   alongside the forced one.

2) Response mapping (mapResponseToCompletion): accept an optional
   structuredOutputName. When set, find the matching tool_use block
   in the response and surface JSON.stringify(block.input) as
   choice.message.content. This keeps result.text semantics uniform
   with OpenAI's json_schema response so session.send consumers
   reading result.text get valid JSON regardless of provider.

Existing tool-call flows (caller-provided tools, normal tool_choice,
multi-step agentic loops) are unchanged; the schema mode triggers
only when the marker is set on responseFormat by the
buildResponseFormat adapter (Task 1).

Author: jddunn

src/core/llm/providers/implementations/AnthropicProvider.ts

@@ -440,7 +440,17 @@ export class AnthropicProvider implements IProvider {
       payload,
     );
 
-    return this.mapResponseToCompletion(apiResponse);
+    // Capture the structured-output tool name from the request options
+    // so the response mapper can surface the matching tool_use block's
+    // input as JSON-string content (uniform API across providers).
+    const sf = options.responseFormat as
+      | { _agentosUseToolForStructuredOutput?: boolean; tool?: { name: string } }
+      | undefined;
+    const structuredOutputName = sf?._agentosUseToolForStructuredOutput
+      ? sf.tool?.name
+      : undefined;
+
+    return this.mapResponseToCompletion(apiResponse, structuredOutputName);
   }
 
   /**
@@ -849,6 +859,30 @@ export class AnthropicProvider implements IProvider {
       }
     }
 
+    // --- Schema-driven structured output via forced tool-use ---
+    // Anthropic doesn't have an OpenAI-style response_format with
+    // json_schema. The equivalent is a single forced tool whose
+    // input_schema matches the desired output shape; the model returns
+    // a tool_use block whose input is JSON-validated by Anthropic's
+    // own enforcement.
+    //
+    // The provider-format adapter (structuredOutputFormat.ts) signals
+    // this mode by setting _agentosUseToolForStructuredOutput on the
+    // responseFormat option. The downstream response-mapper detects the
+    // matching block by the tool's name and surfaces its input as the
+    // JSON-string body of the choice's message.
+    const sf = options.responseFormat as
+      | { _agentosUseToolForStructuredOutput?: boolean; tool?: { name: string; input_schema: Record<string, unknown> } }
+      | undefined;
+    if (sf?._agentosUseToolForStructuredOutput && sf.tool) {
+      const existingTools = (payload.tools as Array<Record<string, unknown>>) ?? [];
+      payload.tools = [
+        { name: sf.tool.name, input_schema: sf.tool.input_schema },
+        ...existingTools,
+      ];
+      payload.tool_choice = { type: 'tool', name: sf.tool.name };
+    }
+
     // Pass through any custom model params
     if (options.customModelParams) {
       Object.assign(payload, options.customModelParams);
@@ -1018,12 +1052,15 @@ export class AnthropicProvider implements IProvider {
    * @returns {ModelCompletionResponse} Normalized completion response.
    * @private
    */
-  private mapResponseToCompletion(apiResponse: AnthropicMessagesResponse): ModelCompletionResponse {
+  private mapResponseToCompletion(
+    apiResponse: AnthropicMessagesResponse,
+    structuredOutputName?: string,
+  ): ModelCompletionResponse {
     // Collect text content
     const textParts = apiResponse.content
       .filter(block => block.type === 'text' && block.text)
       .map(block => block.text!);
-    const fullText = textParts.join('');
+    let fullText = textParts.join('');
 
     // Collect tool_use blocks and convert to OpenAI-style tool_calls
     const toolCalls = apiResponse.content
@@ -1037,6 +1074,20 @@ export class AnthropicProvider implements IProvider {
         },
       }));
 
+    // Schema-driven structured output: if the request set a forced tool
+    // for structured output, find the matching tool_use block and surface
+    // its input as JSON-string content. This keeps result.text uniform
+    // with OpenAI's json_schema response (text is valid JSON) for
+    // session.send callers that consume result.text directly.
+    if (structuredOutputName) {
+      const toolBlock = apiResponse.content.find(
+        b => b.type === 'tool_use' && b.name === structuredOutputName,
+      );
+      if (toolBlock?.input !== undefined) {
+        fullText = JSON.stringify(toolBlock.input);
+      }
+    }
+
     const hasToolCalls = toolCalls.length > 0;
     const finishReason = this.mapStopReason(apiResponse.stop_reason);