feat(cli): structured JSONL output for non-interactive mode (ROADMAP 7.7)

[emal-avala]

Summary

Adds --output-format json flag for CI/CD pipelines and tool-chaining. One-shot mode (-p) writes JSONL events to stdout with status messages on stderr.

agent -p "fix the tests" --output-format json | jq 'select(.type == "tool_call")'

Event types

Event	Fields	When
session_start	session_id, model, timestamp	Before first turn
text_delta	content, turn	LLM streams text
thinking	content, turn	Extended thinking
tool_call	tool, input, turn	Tool invocation
tool_result	tool, output, is_error, turn	Tool completes
turn_complete	turn, input_tokens, output_tokens, cost_usd	Turn ends
error	message, turn	Error
session_end	turns, total_cost_usd, exit_code	Session ends

Exit codes

0=success, 1=config, 2=input, 3=tool failure, 4=LLM error, 5=cost limit, 6=turn limit, 7=permission denied.

Architecture

• crates/cli/src/output.rs — OutputFormat enum, ExitCode enum, JsonStreamSink implementing StreamSink
• Wired into the one-shot path in main.rs (~40 lines)
• Validates --output-format json requires --prompt (rejects interactive mode with a clear error)
• Warnings/compact notifications go to stderr, not the JSONL stream

Test plan

• 8 unit tests: event serialization (all types), format parsing, single-line-JSON invariant for multiline content
• cargo fmt --check ✓
• cargo clippy --all-targets -D warnings ✓
• Full CLI test suite (28 integration + 3 smoke) ✓
• Manual E2E: agent -p "echo hello" --output-format json produces parseable JSONL (requires API key)

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[emal-avala]

Self-review: 2 bugs found and fixed (1499ae2)

🔴 Bug 1: Turn tracking was wrong for multi-turn agent runs

state.turn started at 0. on_turn_complete(n) sets it to n — but only fires on the FINAL turn (when there are no tool calls). All intermediate-turn events (text_delta, tool_call, tool_result) emitted turn: 0 throughout the entire multi-turn agent run.

Fix: added on_turn_start(turn: usize) to StreamSink trait (default no-op, zero impact on existing callers). Called at the top of each for turn in 0..max_turns iteration in the query loop. JsonStreamSink::on_turn_start sets state.turn immediately so all events carry the correct 1-indexed turn number.

🟠 Bug 2: on_tool_result used stale tool name

on_tool_start captured tool_name into state.last_tool_name. on_tool_result then emitted this captured name. Problem: with streaming tool execution (read-only tools fire during streaming), on_tool_start for tool B can overwrite last_tool_name before tool A's on_tool_result arrives. The tool_result event would incorrectly name tool B.

Fix: on_tool_result now uses its tool_name parameter directly. Removed the last_tool_name field entirely.

✅ Other review checks (all clean)

Area	Finding
Text mode backward compat	Identical code path; error propagation via ? unchanged
std::process::exit cleanup	One-shot mode has no post-run cleanup; acceptable
Session save	Not affected — session saves happen inside run_turn_with_sink, not after
Exit code coverage	Only Success (0) and LlmError (4) are currently returned. Other codes (1-7) defined for future use — no incorrect mapping
JSONL single-line invariant	Tested with multiline content — serde_json::to_string escapes \n to \\n
Mutex contention	Low risk — one-shot mode is single-turn, lock held briefly per event
schedule run / serve / ACP paths	Untouched, still use their own sinks

New integration tests (6, no API key required)

Test	What it verifies
output_format_appears_in_help	--output-format shows in --help output
output_format_invalid_value_fails	--output-format xml → error with "unknown output format"
output_format_json_without_prompt_fails	JSON mode without --prompt → error with "requires --prompt"
output_format_text_is_default	No --output-format flag → no format parsing error
output_format_json_no_api_key_emits_session_events	No panic; any stdout is valid JSONL
output_format_case_insensitive	--output-format JSON accepted

Final verification

• cargo fmt --check ✓
• cargo clippy --all-targets -D warnings ✓
• 8 unit tests (output module) ✓
• 6 integration tests (output_format) ✓
• 28 config_cli + 14 schedule + 3 smoke tests ✓

Verdict: safe to merge.