[FEATURE] Add output_mode parameter to Task tool to prevent context overflow in multi-agent orchestration

[markojak]

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When orchestrating multi-agent workflows in headless mode (-p), the Task tool returns full agent execution traces (~20-50KB each) to the orchestrator context, causing severe context overflow.

Current behavior:

• Sub-agents run via Task tool return their entire transcript (all tool calls, inputs, outputs)
• With run_in_background: true, output is truncated to 30K chars but still includes full trace
• With 10+ parallel agents, this adds 300K+ tokens to orchestrator context
• Agent system prompts instructing "return minimal output" have no effect - they only affect what the agent writes, not what the CLI emits

Root cause (from CHANGELOG v1.0.17): "We now emit messages from sub-tasks in -p mode (look for the parent_tool_use_id property)"

This design prioritizes observability over token efficiency, which conflicts with multi-agent orchestration patterns. You effectively cannot build a reasonable multi agent system and run it headlessly because of this.

Proposed Solution

Add an output_mode parameter to the Task tool:

interface TaskToolInput { prompt: string; subagent_type: string; run_in_background?: boolean; output_mode?: 'full' | 'minimal' | 'status_only'; // NEW }

full (default) │ Current behavior - full transcript minimal - Only agent's final text response (what it explicitly outputs)
status_only - {status: "complete", output_file: "/path/to/transcript.txt", agent_id: "..."}

Alternative Solutions

Current workaround (working but complex):

1. Launch agents with run_in_background: true
2. Have agents write status files to disk: .status/{phase}/{slug}.json
3. Never use TaskOutput tool - poll status files via Bash instead
4. Read output files on demand

This works but requires significant orchestrator complexity and custom status file conventions. It also takes away the ability for the orchestrator to manage agents properly and introduces a new control plane problem

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

1. Orchestrator receives task: "Explore the repos and find this function"
2. Explore agent finds target repositories
3. Orchestrator launches 10 parallel agents
4. Current: Each agent returns ~30K of transcript, total 300K tokens overflow
5. With feature: Each agent returns ~100 bytes of status, orchestrator reads specific files when needed
6. Orchestrator context stays manageable, pipeline self-heals on failures

Additional Context

CHANGELOG evidence:

• v1.0.17: "We now emit messages from sub-tasks in -p mode"
• v2.0.64: "Unshipped AgentOutputTool and BashOutputTool, in favor of a new unified TaskOutputTool"
• v2.1.0: "Fixed noisy output when background tasks complete" (only affects interactive UI)
• v2.1.2: "Fixed API context overflow...truncating to 30K chars" (partial fix, still too large)

This is a fundamental architectural issue for anyone building multi-agent systems with Claude Code.