feat: stream-driven progress and TTY-gated deadline for explain --generate

Switches Claude CLI invocation to --output-format stream-json with
--include-partial-messages --verbose, rendering real phase updates as
the summary generates:

  Generating checkpoint summary... (transcript: 47.0 KB)
  → Sending request to Anthropic…
  → Anthropic responded (TTFT 1.9s, 35.9k cached input tokens) — generating…
  → Writing summary… (~1.2k tokens)
  ✓ Summary generated (3.1s, 1.9k output tokens)

Replaces the unconditional 30s wall-clock timeout with a TTY-gated
deadline strategy: no deadline interactive (user Ctrl+C with full
progress visibility), idle-based 5min in non-TTY/CI, optional
summary_timeout_seconds settings override.

Adds StreamingTextGenerator optional agent capability interface,
stream NDJSON parser with captured fixtures, summaryProgressWriter
using the existing statusStyles lipgloss helper, idle watchdog with
atomic timestamps, and progress callback threading through summarize.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Entire-Checkpoint: a19df6695459

Author: peyton-alt

cmd/entire/cli/agent/agent.go

@@ -187,6 +187,49 @@ type TextGenerator interface {
 	GenerateText(ctx context.Context, prompt string, model string) (string, error)
 }
 
+// ProgressPhase identifies a coarse stage in streaming text generation.
+type ProgressPhase string
+
+const (
+	// PhaseConnecting is emitted once when the CLI signals it is making the upstream request.
+	PhaseConnecting ProgressPhase = "connecting"
+	// PhaseFirstToken is emitted once when the upstream responds with the first event,
+	// carrying TTFT and input/cache token counts.
+	PhaseFirstToken ProgressPhase = "first-token"
+	// PhaseGenerating is emitted repeatedly as text or thinking deltas arrive.
+	// OutputTokens carries a running estimate based on delta sizes.
+	PhaseGenerating ProgressPhase = "generating"
+	// PhaseDone is emitted once when the final result event is received without error.
+	PhaseDone ProgressPhase = "done"
+)
+
+// GenerationProgress reports a snapshot of streaming text generation progress.
+// Fields not relevant to the current Phase may be zero-valued.
+type GenerationProgress struct {
+	Phase             ProgressPhase
+	OutputTokens      int // running estimate during PhaseGenerating; final at PhaseDone
+	InputTokens       int // populated at PhaseFirstToken
+	CachedInputTokens int // populated at PhaseFirstToken
+	TTFTms            int // time-to-first-token, populated at PhaseFirstToken
+	DurationMs        int // populated at PhaseDone (final result event)
+}
+
+// ProgressFn receives streaming progress updates. It must not block — invoke it
+// from the same goroutine that reads the stream and keep handlers fast.
+type ProgressFn func(GenerationProgress)
+
+// StreamingTextGenerator is an optional interface for text generators whose
+// underlying CLI exposes a streaming output mode. Callers can use AsStreamingTextGenerator
+// to detect support and fall back to plain GenerateText when unavailable.
+type StreamingTextGenerator interface {
+	Agent
+
+	// GenerateTextStreaming invokes the agent's streaming text generation and
+	// calls progress for each phase update. progress may be nil to suppress
+	// reporting. The returned string is the final response text.
+	GenerateTextStreaming(ctx context.Context, prompt, model string, progress ProgressFn) (string, error)
+}
+
 // HookResponseWriter is implemented by agents that support structured hook responses.
 // Agents that implement this can output messages (e.g., banners) to the user via
 // the agent's response protocol. For example, Claude Code outputs JSON with a

cmd/entire/cli/agent/capabilities.go

@@ -21,6 +21,7 @@ type DeclaredCaps struct {
 	TranscriptPreparer     bool `json:"transcript_preparer"`
 	TokenCalculator        bool `json:"token_calculator"`
 	TextGenerator          bool `json:"text_generator"`
+	StreamingTextGenerator bool `json:"streaming_text_generator"`
 	HookResponseWriter     bool `json:"hook_response_writer"`
 	SubagentAwareExtractor bool `json:"subagent_aware_extractor"`
 }
@@ -105,6 +106,22 @@ func AsTextGenerator(ag Agent) (TextGenerator, bool) { //nolint:ireturn // type-
 	return tg, true
 }
 
+// AsStreamingTextGenerator returns the agent as StreamingTextGenerator if it both
+// implements the interface and (for CapabilityDeclarer agents) has declared the capability.
+func AsStreamingTextGenerator(ag Agent) (StreamingTextGenerator, bool) { //nolint:ireturn // type-assertion helper must return interface
+	if ag == nil {
+		return nil, false
+	}
+	stg, ok := ag.(StreamingTextGenerator)
+	if !ok {
+		return nil, false
+	}
+	if cd, ok := ag.(CapabilityDeclarer); ok {
+		return stg, cd.DeclaredCapabilities().StreamingTextGenerator
+	}
+	return stg, true
+}
+
 // AsHookResponseWriter returns the agent as HookResponseWriter if it both
 // implements the interface and (for CapabilityDeclarer agents) has declared the capability.
 func AsHookResponseWriter(ag Agent) (HookResponseWriter, bool) { //nolint:ireturn // type-assertion helper must return interface

cmd/entire/cli/agent/capabilities_test.go

@@ -94,6 +94,20 @@ func (m *mockFullAgent) CalculateTotalTokenUsage([]byte, int, string) (*TokenUsa
 	return nil, nil //nolint:nilnil // test mock
 }
 
+// StreamingTextGenerator
+func (m *mockFullAgent) GenerateTextStreaming(context.Context, string, string, ProgressFn) (string, error) {
+	return "", nil
+}
+
+// mockBuiltinStreamingAgent is a built-in agent that implements StreamingTextGenerator but NOT CapabilityDeclarer.
+type mockBuiltinStreamingAgent struct {
+	mockBaseAgent
+}
+
+func (m *mockBuiltinStreamingAgent) GenerateTextStreaming(context.Context, string, string, ProgressFn) (string, error) {
+	return "", nil
+}
+
 // mockBuiltinPromptAgent is a built-in agent that implements PromptExtractor but NOT CapabilityDeclarer.
 type mockBuiltinPromptAgent struct {
 	mockBaseAgent
@@ -371,3 +385,43 @@ func TestAsPromptExtractor(t *testing.T) {
 		}
 	})
 }
+
+func TestAsStreamingTextGenerator(t *testing.T) {
+	t.Parallel()
+
+	t.Run("not implemented", func(t *testing.T) {
+		t.Parallel()
+		ag := &mockBaseAgent{}
+		_, ok := AsStreamingTextGenerator(ag)
+		if ok {
+			t.Error("expected false for agent not implementing StreamingTextGenerator")
+		}
+	})
+
+	t.Run("builtin agent", func(t *testing.T) {
+		t.Parallel()
+		ag := &mockBuiltinStreamingAgent{}
+		stg, ok := AsStreamingTextGenerator(ag)
+		if !ok || stg == nil {
+			t.Error("expected true for built-in agent implementing StreamingTextGenerator")
+		}
+	})
+
+	t.Run("declared true", func(t *testing.T) {
+		t.Parallel()
+		ag := &mockFullAgent{caps: DeclaredCaps{StreamingTextGenerator: true}}
+		stg, ok := AsStreamingTextGenerator(ag)
+		if !ok || stg == nil {
+			t.Error("expected true when capability declared true")
+		}
+	})
+
+	t.Run("declared false", func(t *testing.T) {
+		t.Parallel()
+		ag := &mockFullAgent{caps: DeclaredCaps{StreamingTextGenerator: false}}
+		_, ok := AsStreamingTextGenerator(ag)
+		if ok {
+			t.Error("expected false when capability declared false")
+		}
+	})
+}

cmd/entire/cli/agent/claudecode/claude_test.go

@@ -4,7 +4,10 @@ import (
 	"context"
 	"errors"
 	"os/exec"
+	"strings"
 	"testing"
+
+	"github.com/entireio/cli/cmd/entire/cli/agent"
 )
 
 func TestResolveSessionFile(t *testing.T) {
@@ -26,34 +29,56 @@ func TestProtectedDirs(t *testing.T) {
 	}
 }
 
-func TestGenerateText_ArrayResponse(t *testing.T) {
+func TestGenerateTextStreaming_SuccessEmitsPhases(t *testing.T) {
 	t.Parallel()
-	ag := &ClaudeCodeAgent{
-		CommandRunner: func(ctx context.Context, _ string, _ ...string) *exec.Cmd {
-			response := `[{"type":"system","subtype":"init"},{"type":"assistant","message":"Working on it"},{"type":"result","result":"final generated text"}]`
-			return exec.CommandContext(ctx, "sh", "-c", "printf '%s' '"+response+"'")
-		},
-	}
-
-	result, err := ag.GenerateText(context.Background(), "prompt", "")
+	body := strings.Join([]string{
+		`{"type":"system","subtype":"status","status":"requesting"}`,
+		`{"type":"stream_event","event":{"type":"message_start","ttft_ms":1500,"message":{"usage":{"input_tokens":10,"cache_read_input_tokens":2000}}}}`,
+		`{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"hello world"}}}`,
+		`{"type":"result","subtype":"success","is_error":false,"result":"hello world","duration_ms":1700}`,
+	}, "\n")
+	ag := newAgentWithStdout(body)
+	var phases []agent.ProgressPhase
+	got, err := ag.GenerateTextStreaming(context.Background(), "p", "", func(p agent.GenerationProgress) {
+		phases = append(phases, p.Phase)
+	})
 	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
+		t.Fatalf("err = %v; want nil", err)
+	}
+	if got != "hello world" {
+		t.Fatalf("got = %q; want %q", got, "hello world")
+	}
+	want := []agent.ProgressPhase{agent.PhaseConnecting, agent.PhaseFirstToken, agent.PhaseGenerating, agent.PhaseDone}
+	if !equalPhases(phases, want) {
+		t.Fatalf("phases = %v; want %v", phases, want)
 	}
+}
 
-	if result != "final generated text" {
-		t.Fatalf("GenerateText() = %q, want %q", result, "final generated text")
+func TestGenerateTextStreaming_EnvelopeErrorReturnsClaudeError(t *testing.T) {
+	t.Parallel()
+	body := strings.Join([]string{
+		`{"type":"system","subtype":"status","status":"requesting"}`,
+		`{"type":"result","subtype":"success","is_error":true,"api_error_status":401,"result":"Auth required"}`,
+	}, "\n")
+	ag := newAgentWithStdout(body)
+	_, err := ag.GenerateTextStreaming(context.Background(), "p", "", nil)
+	var ce *ClaudeError
+	if !errors.As(err, &ce) {
+		t.Fatalf("err = %v; want *ClaudeError", err)
+	}
+	if ce.Kind != ClaudeErrorAuth {
+		t.Fatalf("Kind = %v; want %v", ce.Kind, ClaudeErrorAuth)
 	}
 }
 
-func TestGenerateText_EnvelopeErrorReturnsClaudeError(t *testing.T) {
+func TestGenerateTextStreaming_StderrAuthFallback(t *testing.T) {
 	t.Parallel()
 	ag := &ClaudeCodeAgent{
 		CommandRunner: func(ctx context.Context, _ string, _ ...string) *exec.Cmd {
-			response := `{"type":"result","subtype":"success","is_error":true,"api_error_status":401,"result":"Auth required"}`
-			return exec.CommandContext(ctx, "sh", "-c", "printf '%s' '"+response+"'")
+			return exec.CommandContext(ctx, "sh", "-c", "printf 'Invalid API key' 1>&2; exit 2")
 		},
 	}
-	_, err := ag.GenerateText(context.Background(), "prompt", "")
+	_, err := ag.GenerateTextStreaming(context.Background(), "p", "", nil)
 	var ce *ClaudeError
 	if !errors.As(err, &ce) {
 		t.Fatalf("err = %v; want *ClaudeError", err)
@@ -63,14 +88,14 @@ func TestGenerateText_EnvelopeErrorReturnsClaudeError(t *testing.T) {
 	}
 }
 
-func TestGenerateText_CLIMissing(t *testing.T) {
+func TestGenerateTextStreaming_CLIMissing(t *testing.T) {
 	t.Parallel()
 	ag := &ClaudeCodeAgent{
 		CommandRunner: func(ctx context.Context, _ string, _ ...string) *exec.Cmd {
 			return exec.CommandContext(ctx, "/nonexistent/binary/that/does/not/exist")
 		},
 	}
-	_, err := ag.GenerateText(context.Background(), "prompt", "")
+	_, err := ag.GenerateTextStreaming(context.Background(), "p", "", nil)
 	var ce *ClaudeError
 	if !errors.As(err, &ce) {
 		t.Fatalf("err = %v; want *ClaudeError", err)
@@ -80,19 +105,37 @@ func TestGenerateText_CLIMissing(t *testing.T) {
 	}
 }
 
-func TestGenerateText_StderrAuthFallback(t *testing.T) {
+func TestGenerateText_DelegatesToStreaming(t *testing.T) {
 	t.Parallel()
-	ag := &ClaudeCodeAgent{
+	body := `{"type":"result","subtype":"success","is_error":false,"result":"ok"}`
+	ag := newAgentWithStdout(body)
+	got, err := ag.GenerateText(context.Background(), "p", "")
+	if err != nil {
+		t.Fatalf("err = %v; want nil", err)
+	}
+	if got != "ok" {
+		t.Fatalf("got = %q; want %q", got, "ok")
+	}
+}
+
+// newAgentWithStdout returns a ClaudeCodeAgent whose CommandRunner produces a
+// subprocess that prints the given body to stdout and exits 0.
+func newAgentWithStdout(body string) *ClaudeCodeAgent {
+	return &ClaudeCodeAgent{
 		CommandRunner: func(ctx context.Context, _ string, _ ...string) *exec.Cmd {
-			return exec.CommandContext(ctx, "sh", "-c", "printf 'Invalid API key' 1>&2; exit 2")
+			return exec.CommandContext(ctx, "sh", "-c", "cat <<'ENDOFSTREAM'\n"+body+"\nENDOFSTREAM")
 		},
 	}
-	_, err := ag.GenerateText(context.Background(), "prompt", "")
-	var ce *ClaudeError
-	if !errors.As(err, &ce) {
-		t.Fatalf("err = %v; want *ClaudeError", err)
+}
+
+func equalPhases(a, b []agent.ProgressPhase) bool {
+	if len(a) != len(b) {
+		return false
 	}
-	if ce.Kind != ClaudeErrorAuth {
-		t.Fatalf("Kind = %v; want %v", ce.Kind, ClaudeErrorAuth)
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
 	}
+	return true
 }