Add support for output-format stream-jsonflag for headless mode

[anj-s]

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

	🍏	🪟	🐧
npm run	✅	❓	❓
npx	❓	❓	❓
Docker	❓	❓	❓
Podman	❓	-	-
Seatbelt	❓	-	-

Linked issues / bugs

fixes #8203

[github-actions]

Size Change: +8.72 kB (+0.05%)

Total Size: 17.8 MB

Filename	Size	Change
./bundle/gemini.js	17.8 MB	+8.72 kB (+0.05%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB
./bundle/sandbox-macos-permissive-open.sb	830 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB

_{compressed-size-action}

[jerop]

Excited for this feature, thanks @anj-s!

I was expecting this new mode to be an option on the existing --output-format flag. Right now, we have --output-format which accepts text and json. This new mode would be --output-format=stream-json, keeping all output-related formats under a single, consistent flag.

.option('output-format', {
  type: 'string',
  description: 'The output format for the response.',
  choices: ['text', 'json', 'stream-json'],
})

Was there a specific reason for introducing a new, separate --stream-format=output-json flag instead of extending the existing one?

Overall, this looks great - I'm happy to approve once we clarify the configuration.

OOO