feat(release): ship claude native structured outputs

Requested removing the legacy JSON prompt fallback so Claude structured outputs rely on the Agent SDK's native schema enforcement. The Claude adapter now always requests json_schema outputFormat, extracts structured_output from result frames, and the sample test asserts this behavior. Documented the change in the changelog, bumped every package to 0.19.0 (updating peer ranges and locks), and rebuilt the Claude adapter to ensure the new flow compiles.

Author: OhadAssulin

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.19.0] - 2025-11-19
+### ✨ Claude Native Structured Outputs
+- `@headless-coder-sdk/claude-adapter` now relies entirely on Claude Agent SDK's native `structured_output`, removing the legacy prompt-based JSON parsing fallback so schemas are enforced by Claude itself.
+- Claude structured output example asserts that `structured_output` is returned, ensuring future regressions are caught by CI.
+
+### 📦 Versioning
+- Bumped every package to `0.19.0` to publish the native structured output change and keep dependencies aligned.
+
 ## [0.18.0] - 2025-11-14
 ### 🚀 Codex & Model Updates
 - Codex adapter is now built against `@openai/codex-sdk@0.58.0`, unlocking GPT-5.1 Codex and GPT-5.1 Modals support out of the box.

examples/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@headless-coder-sdk/examples-tests",
   "private": true,
-  "version": "0.1.0",
+  "version": "0.19.0",
   "type": "module",
   "main": "src/codex-web-calculator.test.ts",
   "files": [

examples/src/claude-structured-output.test.ts

@@ -73,6 +73,8 @@ async function runClaudeStructured(t: TestContext): Promise<void> {
   assert.equal(typeof structured.summary, 'string');
   assert.ok(Array.isArray(structured.risks));
   assert.ok(structured.risks.length >= 1);
+  assert.ok(result.raw?.structured_output, 'Claude should return native structured output payloads.');
+  assert.deepEqual(result.raw?.structured_output, structured);
 }
 
 test('claude returns structured output', runClaudeStructured);

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "headless-coder-sdk",
   "private": true,
-  "version": "0.1.0",
+  "version": "0.19.0",
   "type": "module",
   "workspaces": [
     "packages/*",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/acp-server",
-  "version": "0.12.0",
+  "version": "0.19.0",
   "type": "module",
   "scripts": {
     "dev": "next dev -p 8000",

packages/acp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/claude-adapter",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -19,7 +19,7 @@
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": ">=0.1.46",
-    "@headless-coder-sdk/core": "^0.18.0"
+    "@headless-coder-sdk/core": "^0.19.0"
   },
   "devDependencies": {
     "typescript": "^5.4.0",

packages/claude-adapter/package.json

@@ -61,28 +61,12 @@ interface ActiveClaudeRun {
   abortReason?: string;
 }
 
-const STRUCTURED_OUTPUT_SUFFIX =
-  'You must respond with valid JSON that satisfies the provided schema. Do not include prose before or after the JSON.';
-
 function ensureNodeRuntime(action: string): void {
   if (!isNodeRuntime) {
     throw new Error(`@headless-coder-sdk/claude-adapter can only ${action} inside Node.js.`);
   }
 }
 
-function applyOutputSchemaPrompt(input: PromptInput, schema?: object): PromptInput {
-  if (!schema) return input;
-  const schemaSnippet = JSON.stringify(schema, null, 2);
-  const systemPrompt = `${STRUCTURED_OUTPUT_SUFFIX}\nSchema:\n${schemaSnippet}`;
-  if (typeof input === 'string') {
-    return `${input}\n\n${systemPrompt}`;
-  }
-  return [
-    { role: 'system', content: systemPrompt },
-    ...input,
-  ];
-}
-
 function shouldUseNativeStructuredOutput(schema?: object): boolean {
   return !!schema;
 }
@@ -98,20 +82,6 @@ function extractNativeStructuredOutput(result: any): unknown | undefined {
   return undefined;
 }
 
-function extractJsonPayload(text: string | undefined): unknown | undefined {
-  if (!text) return undefined;
-  const fenced = text.match(/```json\s*([\s\S]+?)```/i);
-  const candidate = (fenced ? fenced[1] : text).trim();
-  const start = candidate.indexOf('{');
-  const end = candidate.lastIndexOf('}');
-  if (start === -1 || end === -1 || end < start) return undefined;
-  try {
-    return JSON.parse(candidate.slice(start, end + 1));
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * Normalises prompt input into Claude's string format.
  *
@@ -237,8 +207,7 @@ export class ClaudeAdapter implements HeadlessCoder {
     const state = thread.internal as ClaudeThreadState;
     this.assertIdle(state);
     const useNativeStructuredOutput = shouldUseNativeStructuredOutput(runOpts?.outputSchema);
-    const promptInput = useNativeStructuredOutput ? input : applyOutputSchemaPrompt(input, runOpts?.outputSchema);
-    const prompt = toPrompt(promptInput);
+    const prompt = toPrompt(input);
     const options = this.buildOptions(state, runOpts, useNativeStructuredOutput);
     const generator = query({ prompt, options });
     const active = this.registerRun(state, generator, runOpts?.signal);
@@ -279,9 +248,7 @@ export class ClaudeAdapter implements HeadlessCoder {
     if (finalResult && claudeResultIndicatesError(finalResult)) {
       throw new Error(buildClaudeResultErrorMessage(finalResult));
     }
-    const structured = runOpts?.outputSchema
-      ? extractNativeStructuredOutput(finalResult) ?? extractJsonPayload(lastAssistant)
-      : undefined;
+    const structured = runOpts?.outputSchema ? extractNativeStructuredOutput(finalResult) : undefined;
     return { threadId: state.sessionId, text: lastAssistant, raw: finalResult, json: structured };
   }
 
@@ -308,8 +275,7 @@ export class ClaudeAdapter implements HeadlessCoder {
     const state = thread.internal as ClaudeThreadState;
     this.assertIdle(state);
     const useNativeStructuredOutput = shouldUseNativeStructuredOutput(runOpts?.outputSchema);
-    const promptInput = useNativeStructuredOutput ? input : applyOutputSchemaPrompt(input, runOpts?.outputSchema);
-    const prompt = toPrompt(promptInput);
+    const prompt = toPrompt(input);
     const options = this.buildOptions(state, runOpts, useNativeStructuredOutput);
     const generator = query({ prompt, options });
     const adapter = this;

packages/claude-adapter/src/index.ts

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/codex-adapter",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -27,7 +27,7 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@headless-coder-sdk/core": "^0.18.0",
+    "@headless-coder-sdk/core": "^0.19.0",
     "@openai/codex-sdk": "^0.58.0"
   },
   "devDependencies": {

packages/codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-coder-sdk/core",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Unified SDK for headless AI coders (Codex, Claude, Gemini) with standardized threading, streaming, and sandboxing.",
   "type": "module",
   "main": "./dist/index.cjs",