feat: propagate sub-agent internal events in --output-format stream-json

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 using claude -p --output-format stream-json --verbose, the Agent tool's internal events (thinking, tool_use, tool_result from sub agents) are not propagated to the parent's stream. Only the top-level tool_use (Agent call) and tool_result (final output) are visible, leaving a 5+ minute black box during sub-agent execution. This makes real-time observability of multi-agent workflows impossible for production systems using Claude Code as a backend.

Proposed Solution

Propagate sub-agent events to the parent stream-json output, wrapped to identify the source. Two possible approaches:

Option A — New event type: {"type": "subagent", "task_id": "abc123", "event": {"type": "assistant", "message": {"content": [{"type": "thinking", "thinking":"..."}]}}}

Option B — Flag on existing events: {"type": "assistant", "parent_tool_use_id": "toolu_01JTG...", "task_id": "abc123", "message": ...}

Activation: a new flag --propagate-subagent-events, or automatically included when --verbose is set (since verbose already implies maximum detail).

This would expose the sub-agent's thinking blocks, tool_use calls (Bash, Read, Write, Agent), and tool_result responses in real-time as they happen — enabling full hierarchical tracing without replacing the built-in Agent tool with manual subprocess management.

Alternative Solutions

We currently parse task_started, task_notification, and tool_use_result metadata from the parent stream, which gives us start/end timestamps, total tokens, tool use count, and duration per sub-agent. This provides a summary but no internal breakdown.

The only alternative is to stop using the built-in Agent tool entirely and manage sub-agents ourselves via separate claude -p subprocesses, each with --output-format stream-json. This works but defeats the purpose of the Agent tool (automatic worktree isolation, model selection, context passing) and adds significant complexity to the orchestration layer.

A middle ground would be emitting at least the sub-agent's tool_use events (not thinking) to the parent stream — this would give visibility into what tools are being called without exposing internal reasoning.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

We run a multi-agent Slack bot platform (3 agents) powered by Claude Code. Each Slack message triggers claude -p with --output-format stream-json. A streaming parser creates hierarchical Langfuse traces in real-time.

Example: user sends "implement the /funds endpoint". The orchestrator agent thinks, then spawns Agent(subagent_type="dev-py", model="opus", prompt="implement /funds...").

What we see in Langfuse today:
thinking.1: "I'll delegate to dev-py with opus" (0.1s)
tool.Agent: {subagent_type: "dev-py", model: "opus"} (304s, output: null)

What we'd like to see:
thinking.1: "I'll delegate to dev-py with opus" (0.1s)
tool.Agent: {subagent_type: "dev-py", model: "opus"}
└─ subagent.thinking: "Let me read the codebase first"
└─ subagent.tool.Read: {file: "src/routes.py"} (0.5s)
└─ subagent.tool.Bash: {command: "npm test"} (12s)
└─ subagent.thinking: "Tests pass, now implementing"
└─ subagent.tool.Write: {file: "src/funds.py"} (0.3s)
└─ result: "Endpoint implemented, PR #91 created" (304s total)

This enables: per-tool latency breakdown, stuck process detection, cost attribution per sub-agent, and full audit trail — all
critical for production multi-agent systems.

Additional Context

Environment: Claude Code 2.1.84, macOS (Apple Silicon), agents run via claude -p with --dangerously-skip-permissions --output-format
stream-json --verbose.

We discovered through testing that stream-json already emits rich Agent metadata:

• system/task_started: task_id, tool_use_id, description, task_type, prompt
• system/task_notification: status, total_tokens, tool_uses, duration_ms
• user/tool_use_result: agentType, content, totalDurationMs, totalTokens, totalToolUseCount, full usage breakdown (input/output/cache

tokens)

This is excellent — the infrastructure for sub-agent awareness already exists in the stream. The missing piece is propagating the
sub-agent's own stream events (thinking, tool_use, tool_result) to the parent, which would complete the observability picture.

Project: https://github.com/nelsonfrugeri-tech/bike-shop (the platform that consumes Claude Code as backend)