feat(claude): expose agent.output_format for structured output

[col]

Adds an optional agent.output_format key to the POST /api/initialise manifest, letting a caller constrain a Claude turn's output to a JSON Schema. Maps onto claude.outputFormat, which a2a-wrapper#33 added and @col/a2a-claude@0.2.1-beta.6 ships.

Spec: docs/superpowers/specs/2026-08-18-claude-output-format-design.md
Plan: docs/superpowers/plans/2026-08-18-claude-output-format.md

What it looks like

"agent": {
  "platform": "claude",
  "output_format": {
    "type": "json_schema",
    "schema": { "type": "object", "properties": { "status": { "type": "string" } } }
  }
}

Omitting the key leaves the wrapper's freeform-text default in place, so no existing manifest changes behaviour.

Validation contract

Throng validates the wrapper shape only:

Input	Result
not an object, or type !== "json_schema"	400 — agent.output_format
schema missing / not an object / an array	400 — agent.output_format.schema
absent	accepted; outputFormat left unset

The schema body itself is not inspected. Throng doesn't own JSON Schema validity — an invalid schema surfaces from the SDK at turn time, not at initialise.

This duplicates a shape check a2a-claude also performs, deliberately. The wrapper validates inside initialize(), so a bad value there fails the boot after initialise has already returned 202. Validating here turns that into a field-level 400 at the API boundary, consistent with how permission_mode, model, effort and thinking are already handled. The accepted cost is that a future wrapper release adding a second output-format type would be blocked by our whitelist until updated here too.

Verbatim schema pass-through

Only the outer key is renamed (output_format → outputFormat). Unlike thinking.budget_tokens → budgetTokens, nothing rewrites keys inside schema — they're JSON Schema's own vocabulary (additionalProperties, patternProperties, …) and renaming them would corrupt the schema. Tests at both the validation and mapping layers pin this with a nested schema that survives deep-equal.

Operational notes

• The structured result is an additional application/json data part on the response artifact; the text part still publishes first, so text-only clients are unaffected. The data part is only appended when the result is a JSON object — an array or scalar top-level schema produces no data part.
• An unsatisfiable schema fails the turn with "Structured output retries exhausted." rather than degrading to freeform output. That usually means a schema bug, though the SDK reports the same exhaustion when structured output is retracted by a model fallback.

One claim was deliberately not made: whether the text part carries the JSON payload instead of prose under a structured format. result and structured_output are independent fields on SDKResultSuccess and nothing in the SDK or wrapper documents one replacing the other, so the docs assert only what's established. Worth confirming with a live turn before anyone relies on the text part's contents.

Verification

npm run build, npm run typecheck, npm test -- --force all pass from the repo root — 7/7 turbo tasks, 364 tests (249 core, 87 claude, 22 codex, 6 agent).

Out of scope

No default schema — Throng ships none, the manifest producer decides. No changes to packages/core, throng-agent, or throng-agent-codex. No other unexposed ClaudeConfig field wired up.

🤖 Generated with Claude Code

https://claude.ai/code/session_01My4JH7AAyLhe9Hb5626Gdv