TLDR

Adds --output-format stream-json flag for non-interactive mode, enabling real-time JSONL event streaming. This allows external tools and scripts to monitor AI agent progress in real-time instead of waiting for a single JSON response at the end.

Dive Deeper

Key features:

• Emits 6 event types: init, message, tool_use, tool_result, error, result
• Newline-delimited JSON (JSONL) format for easy parsing
• Real-time streaming as events occur (not batched)
• Fully backward compatible - existing --output-format json unchanged

Event sequence example:

{"type":"init","timestamp":"...","session_id":"abc123","model":"gemini-2.0-flash-exp"}
{"type":"message","role":"user","content":"List files","timestamp":"..."}
{"type":"tool_use","tool_name":"Bash","tool_id":"bash-123","parameters":{"command":"ls"},"timestamp":"..."}
{"type":"tool_result","tool_id":"bash-123","status":"success","output":"file1.txt\nfile2.txt","timestamp":"..."}
{"type":"message","role":"assistant","content":"Here are the files...","delta":true,"timestamp":"..."}
{"type":"result","status":"success","stats":{"total_tokens":100,"input_tokens":50,"output_tokens":50,"duration_ms":1200,"tool_calls":1},"timestamp":"..."}

Documentation:
Added to README.md and docs/

Reviewer Test Plan

# 1. Build the project
npm run build:all

# 2. Test basic streaming
echo "What is 2+2?" | npm run start -- --output-format stream-json

# Expected: See init, message (user), message (assistant with delta:true), result events

# 3. Test tool usage
npm run start -- --output-format stream-json --prompt "List files in current directory"

# Expected: See tool_use and tool_result events in addition to messages

# 4. Parse with jq
npm run start -- --output-format stream-json --prompt "Hello" | jq .

Testing Matrix

Linked issues / bugs

fixes #8203