Problem or Motivation
When running in headless mode with --output-format text, users have no visibility into what the agent is doing during long-running operations. If the agent calls multiple tools (e.g., reading files, validating a template, deploying a stack), the user sees nothing until the final text response is printed — which can take 30+ seconds for complex tasks.
This makes it difficult to:
- Know if the process is stuck or making progress
- Understand what tools are being invoked
- Estimate how long the operation will take
Proposed Solution
Add a --verbose / -V flag for headless mode that outputs tool activity to stderr while keeping the clean text response on stdout:
# Default: only final text on stdout (current behavior)
iac-code -p "Deploy a VPC" --output-format text
# Verbose: tool progress on stderr, final text on stdout
iac-code -p "Deploy a VPC" --output-format text --verbose
Stderr output (verbose):
[tool] skill: iac-aliyun (inline)
[tool] read_file: /path/to/references/ros-template.md
[tool] write_file: /tmp/vpc-template.yml
[tool] aliyun_api: ROS ValidateTemplate ✓ (1.2s)
[tool] ros_stack: CreateStack → CREATING (stack-id: abc123)
For stream-json format, tool start/end events are already emitted. For text format, the verbose flag would write a one-line summary per tool call to stderr.
Alternatives Considered
- Always showing progress in text mode (too noisy for piped/scripted usage)
- Using
stream-json and parsing events (works but complex for simple automation scripts)
- Adding a
--progress format that only shows tool names without full JSON events
Related Area
CLI / Interactive Mode
Additional Context
The StreamJsonWriter already emits ToolUseStartEvent and ToolResultEvent with all needed data. The implementation would add a lightweight stderr writer that TextWriter delegates to when verbose mode is enabled. This keeps stdout clean for piping while giving operators visibility into agent activity.
Problem or Motivation
When running in headless mode with
--output-format text, users have no visibility into what the agent is doing during long-running operations. If the agent calls multiple tools (e.g., reading files, validating a template, deploying a stack), the user sees nothing until the final text response is printed — which can take 30+ seconds for complex tasks.This makes it difficult to:
Proposed Solution
Add a
--verbose/-Vflag for headless mode that outputs tool activity to stderr while keeping the clean text response on stdout:Stderr output (verbose):
For
stream-jsonformat, tool start/end events are already emitted. Fortextformat, the verbose flag would write a one-line summary per tool call to stderr.Alternatives Considered
stream-jsonand parsing events (works but complex for simple automation scripts)--progressformat that only shows tool names without full JSON eventsRelated Area
CLI / Interactive Mode
Additional Context
The
StreamJsonWriteralready emitsToolUseStartEventandToolResultEventwith all needed data. The implementation would add a lightweight stderr writer thatTextWriterdelegates to when verbose mode is enabled. This keeps stdout clean for piping while giving operators visibility into agent activity.