#3858·crush

Support caller-provided JSON Schema for `crush run`

Author: jonas-srlabsCreated Sep 16, 2026Updated Sep 16, 2026

Description

Request

Add a --json-schema <path> option to crush run. The supplied schema should constrain the final model response after the tool loop through the provider's native structured-output API.

bash
crush run --json-schema response.schema.json "Complete this task"

Without this option, the final response remains text. With it, Crush prints a JSON document matching the schema.

Other coding agents already support schema enforcement:

bash
claude -p --json-schema '{"type":"object", ...}' "Complete this task"
codex exec --output-schema response.schema.json "Complete this task"

For providers with native schema enforcement, Crush should forward the schema through the provider API. For example:

Anthropic:

json
{
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {}
    }
  }
}

OpenAI:

json
{
  "text": {
    "format": {
      "type": "json_schema",
      "name": "crush_output",
      "strict": true,
      "schema": {}
    }
  }
}

References: Anthropic structured outputs, OpenAI Responses API.

If the selected provider or model cannot enforce the supplied schema, crush run should return a clear error.

Related JSON output

This moves in the same direction as #1034, which requests a machine-readable output format for the complete Crush run. The two features serve different purposes:

  • --json-schema constrains the model response.
  • --output-format json wraps that response with execution metadata.

The future JSON output could contain the complete parsed, schema-constrained model response directly in result:

json
{
  "result": {
    "answer": "Task completed."
  },
  "usage": {
    "input_tokens": 123,
    "output_tokens": 45
  },
  "model": "...",
  "provider": "...",
  "session_id": "..."
}