feat(claude-code): stream-json parser tap for the unified harness surface

[declan-scale]

Summary

• Ports the golden agent's _StreamJsonProcessor to a pure SDK tap: convert_claude_code_to_agentex_events + ClaudeCodeTurn + usage normalization (claude_code_usage_to_turn_usage)
• Cross-channel conformance fixtures (text-only, tool-call-result, thinking-block, multi-step) added to the shared conformance runner
• Orchestration (sandbox/secret/MCP) stays in the golden agent; no deployable agent is added and no CI live-matrix row is needed

🤖 Generated with Claude Code

Greptile Summary

This PR ports the golden agent's _StreamJsonProcessor to a reusable SDK tap — convert_claude_code_to_agentex_events + ClaudeCodeTurn — that converts Claude Code's stream-json stdout into canonical StreamTaskMessage* events consumable by the unified harness. Three tutorial agents (sync, async-base, async-Temporal) are added to demonstrate the tap wired to a real subprocess, along with a comprehensive unit-test suite and cross-channel conformance fixtures.

• _claude_code_sync.py: stateful async generator that maps all envelope types (assistant/user content blocks, stream_event triples, result) to harness events; per-block dedup via _streamed_block_indexes correctly handles multi-turn and multi-thinking-block streams.
• _claude_code_turn.py: ClaudeCodeTurn wraps the generator as a HarnessTurn; claude_code_usage_to_turn_usage defensively maps all known CLI usage key shapes and preserves real zeros vs. absent fields.
• Tutorial agents: all three use an injectable _spawn_claude seam with concurrent stderr drain and try/finally subprocess/task cleanup, resolving the deadlock and leak concerns from the prior review pass.

Confidence Score: 5/5

Safe to merge; all blocking issues from the previous review pass are addressed and no new defects were found.

The per-block streaming dedup, multi-thinking-block index claiming, stderr deadlock, and subprocess/task leak are all correctly resolved. The remaining observations are cleanup items that do not affect correctness or runtime behaviour.

No files require special attention.

Important Files Changed

Filename	Overview
src/agentex/lib/adk/_modules/_claude_code_sync.py	Core stream-json parser tap; previous issues (per-block dedup, thinking-stream reset, stderr deadlock) are all addressed. Two unused accumulation buffers (_text_buf, _thinking_buf) and the tool-response name gap remain as minor cleanup items.
src/agentex/lib/adk/_modules/_claude_code_turn.py	ClaudeCodeTurn and usage normalization; defensive handling of all known cost/usage key shapes, correct lazy iterator caching, and clean protocol conformance assertion.
tests/lib/adk/test_claude_code_sync.py	Comprehensive unit tests covering text, thinking, tool calls/results, multi-turn dedup, on_result callback, and index monotonicity.
tests/lib/core/harness/conformance/test_claude_code_conformance.py	Cross-channel conformance fixtures; _run_pure_async correctly replaces asyncio.run() to avoid running-loop conflicts, but lacks explicit coroutine cleanup on unexpected exceptions.
examples/tutorials/00_sync/060_claude_code/project/acp.py	Sync tutorial ACP handler; stderr deadlock and subprocess/task-leak issues from previous review are resolved with concurrent stderr drain and try/finally cleanup.
examples/tutorials/10_async/10_temporal/140_claude_code/project/activities.py	Temporal activity spawning claude CLI; correctly passes session_id for multi-turn resume, identical subprocess cleanup pattern as sync/async tutorials.
examples/tutorials/10_async/10_temporal/140_claude_code/project/workflow.py	Temporal workflow persisting session_id across turns for multi-turn Claude Code sessions; correctly delegates subprocess I/O to an activity.
src/agentex/lib/core/harness/types.py	Minor addition of HarnessTurn protocol and TurnUsage/TurnResult models; clean and backwards-compatible.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant CLI as claude CLI (stdout)
    participant Tap as convert_claude_code_to_agentex_events
    participant Turn as ClaudeCodeTurn
    participant Emitter as UnifiedEmitter

    CLI->>Tap: stream_event / content_block_start(text)
    Tap->>Emitter: StreamTaskMessageStart(TextContent)
    CLI->>Tap: stream_event / content_block_delta(text_delta)
    Tap->>Emitter: StreamTaskMessageDelta(TextDelta)
    CLI->>Tap: stream_event / content_block_stop
    Tap->>Emitter: StreamTaskMessageDone

    CLI->>Tap: assistant tool_use block
    Tap->>Emitter: StreamTaskMessageStart(ToolRequestContent)
    Tap->>Emitter: StreamTaskMessageDone

    CLI->>Tap: user tool_result block
    Tap->>Emitter: StreamTaskMessageFull(ToolResponseContent)

    CLI->>Tap: result envelope
    Tap->>Turn: on_result stores _result_envelope
    Turn->>Emitter: usage() returns TurnUsage after stream exhausted

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant CLI as claude CLI (stdout)
    participant Tap as convert_claude_code_to_agentex_events
    participant Turn as ClaudeCodeTurn
    participant Emitter as UnifiedEmitter

    CLI->>Tap: stream_event / content_block_start(text)
    Tap->>Emitter: StreamTaskMessageStart(TextContent)
    CLI->>Tap: stream_event / content_block_delta(text_delta)
    Tap->>Emitter: StreamTaskMessageDelta(TextDelta)
    CLI->>Tap: stream_event / content_block_stop
    Tap->>Emitter: StreamTaskMessageDone

    CLI->>Tap: assistant tool_use block
    Tap->>Emitter: StreamTaskMessageStart(ToolRequestContent)
    Tap->>Emitter: StreamTaskMessageDone

    CLI->>Tap: user tool_result block
    Tap->>Emitter: StreamTaskMessageFull(ToolResponseContent)

    CLI->>Tap: result envelope
    Tap->>Turn: on_result stores _result_envelope
    Turn->>Emitter: usage() returns TurnUsage after stream exhausted

Loading

_{Reviews (14): Last reviewed commit: "fix(claude-code): address Greptile revie..." | Re-trigger Greptile}