feat(cli): add --output-format json to wrap single-query agent output

[vitali87]

Closes #250 (reframed scope).

What

Adds a --output-format table|json option to the start command's single-query path (-a/--ask-agent). Default table keeps the current plain-text behavior; json wraps the agent answer so it can be piped into jq:

cgr start -a "What does the parser do?" --output-format json
{"query": "What does the parser do?", "response": "...agent answer..."}

Logs already go to stderr, so stdout stays clean for scripting.

Why this scope

The original issue asked for row-structured {query, results[], count} JSON. cgr's query path is agentic (an LLM RAG agent returns free-form text), not a row query engine, so row-shaped results don't map onto the architecture. Export to JSON already exists (cgr export). The achievable, useful piece is wrapping the single-query answer as JSON, mirroring the existing dead-code --format table|json precedent.

Changes

• constants.py: QueryFormat StrEnum + KEY_QUERY/KEY_RESPONSE
• types_defs.py: QueryJsonOutput TypedDict
• cli_help.py: help text for the new option
• main.py: main_single_query emits JSON when requested
• cli.py: --output-format option on start
• Tests: TDD coverage for default-text and JSON wrapping

[gemini-code-assist]

Code Review

This pull request introduces a new --output-format option to the CLI, allowing users to format the single-query agent response as either plain text (table) or structured JSON (json). This change is supported by new type definitions, constants, and unit tests. The feedback suggests a minor improvement to use ensure_ascii=False when serializing the JSON output to prevent escaping non-ASCII characters, which enhances CLI usability for international users.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[greptile-apps]

Greptile Summary

This PR adds JSON output for single-query agent runs. The main changes are:

• Adds --output-format table|json to cgr start.
• Wraps --ask-agent responses as {query, response} JSON when requested.
• Keeps plain text as the default output.
• Rejects JSON output when --ask-agent is not used.
• Adds tests for text output, JSON output, non-ASCII text, and the invalid option combination.

Confidence Score: 5/5

The change is narrowly scoped to CLI output formatting and includes coverage for the supported and unsupported command combinations.

The implementation appears straightforward, preserves the default text behavior, and tests cover JSON wrapping, Unicode content, and invalid usage.

T-Rex Logs

What T-Rex did

• The runtime blocker was reproduced consistently, showing that only Python 3.11.6 was available in the environment and that python3.12, pyenv, or conda were not present.
• Artifacts captured the actual command output and the import-time failure that occurred before the scenario execution.
• No contract mismatch was reported because the failure was environmental rather than indicating a change in code behavior.

_{Ran code and verified through T-Rex}

_{Reviews (2): Last reviewed commit: "fix(cli): reject --output-format json wi..." | Re-trigger Greptile}

[vitali87]

@greptile review