docs(rfc): Transparent Stream activity display mode (#3820)

[franksong2702]

Doc-only RFC-lite for the display-mode split discussed in #3820. No behavior change.

What

Adds docs/rfcs/transparent-stream-activity-mode.md, proposing Transparent Stream as an opt-in, chronological activity display mode alongside the default Compact Worklog (#3400/#3401/#3741).

Why

#3820 established that the pre-#3401 transparent chronological stream is no longer reachable, and that the existing Compact tool activity toggle (simplified_tool_calling) cannot restore it:

• it is asymmetric — the live path branches on it, but the settled/reload rebuild does not, so tool calls re-collapse into the Activity summary on settle or reload;
• even with it off, the live view is not a usable cockpit stream (the running tool card was pushed out of the viewport while Thinking dominated).

Per the thread (@ai-ag2026, @nesquena), the agreed direction is a real display-mode split, not another overloaded disclosure default. This RFC captures that, the four acceptance criteria, the three concrete integration points, and a sliced rollout plan.

Scope

• Doc-only. No code, no behavior change.
• Per docs/rfcs/README.md, this is a design direction for review, not an invitation to implement fragments. Implementation slices will be confirmed in Major UX regression: restore transparent chronological reasoning/tool-call stream in chat UI #3820 first to avoid duplicating work with @ai-ag2026.

Cross-references the parent contract live-to-final-assistant-replies.md.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This doc-only RFC adds docs/rfcs/transparent-stream-activity-mode.md, proposing an opt-in Transparent Stream display mode alongside the existing Compact Worklog, and registers the new file in the RFC index. No production code is changed.

• The RFC clearly documents why the existing simplified_tool_calling toggle cannot solve the cockpit-stream regression, specifies four acceptance criteria, names three concrete integration points in static/ui.js, and outlines a four-PR rollout with the correct ordering (deterministic settled-path first, live UX later).
• The central normalizeToEvents() abstraction shown in the architecture diagram has no defined event schema, which leaves each implementation slice free to interpret the normalization contract differently — the main substantive gap to address before implementation begins.

Confidence Score: 5/5

Safe to merge — purely documentation, no executable code is touched.

Both changed files are Markdown. The RFC follows all conventions from the README, the README index entry is correctly added, and there are no code, schema, or migration changes. The only substantive gap (unspecified normalizeToEvents() contract) is a design-doc quality concern that ideally gets addressed before implementation PRs open, but it does not block merging the RFC itself.

No files require special attention for merge purposes; the normalizeToEvents() event-schema gap in transparent-stream-activity-mode.md is worth resolving before implementation work starts.

Important Files Changed

Filename	Overview
docs/rfcs/README.md	Adds a one-line entry for the new RFC in the "Current RFCs" list, correctly placed after the parent contract it extends.
docs/rfcs/transparent-stream-activity-mode.md	New RFC document proposing a Transparent Stream display mode; well-structured and follows conventions, but the central normalizeToEvents() abstraction's contract is left unspecified, creating a risk of per-slice divergence across the four implementation PRs.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    P[User preference\nchat_activity_display_mode] -->|compact_worklog| CW[Compact Worklog\ndefault mode]
    P -->|transparent_stream| TS[Transparent Stream\nopt-in mode]

    subgraph Sources["Data sources"]
        SSE[SSE live stream]
        JR[Journal replay]
        SM[Settled messages]
    end

    SSE --> NE["normalizeToEvents()"]
    JR --> NE
    SM --> NE

    NE --> RAE["renderActivityEvent()"]
    RAE --> DOM[DOM output]

    subgraph Integration["Integration points (static/ui.js)"]
        A["A: renderMessages()\nSettled rebuild branch"]
        B["B: ensureLiveWorklogShell()\n+ live event handlers"]
        C["C: Summary bypass\n_syncToolCallGroupSummary() skipped"]
    end

    TS --> A
    TS --> B
    TS --> C

    A --> NE
    B --> NE
    C --> NE

Loading

_{Reviews (2): Last reviewed commit: "docs(rfc): refine Transparent Stream rol..." | Re-trigger Greptile}

[greptile-apps]

RFC not registered in docs/rfcs/README.md

Every other RFC in the directory is listed under the "Current RFCs" section of docs/rfcs/README.md (e.g., live-to-final-assistant-replies.md, webui-pending-intent-controls.md). This new document is absent from that index, making it invisible to anyone who reads the RFC directory via the README rather than browsing the filesystem. A one-line entry pointing to this file and tracking issue #3820 should be added there alongside the others.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[nesquena-hermes]

Reviewed in depth — accepting the direction. 🎉

I read the full #3820 thread and verified the RFC's technical claims against origin/master:

• The cited integration points are real and accurate: renderMessages() tool-call loop (~8613-8657), buildToolCard (9097), _assistantAnchorForActivity (8524), ensureLiveWorklogShell (9430), _syncToolCallGroupSummary / _toolWorklogSummary (8905).
• The core asymmetry claim checks out: the settled tool-call loop unconditionally runs ensureActivityGroup → _syncToolCallGroupSummary with no isSimplifiedToolCalling() branch, so tools re-collapse on settle/reload regardless of the flag — exactly why the existing Compact tool activity toggle can't restore Major UX regression: restore transparent chronological reasoning/tool-call stream in chat UI #3820's transparent stream.
• It faithfully captures the consensus reached with @ai-ag2026 and @nesquena: a real display-mode split, not an overload of the old toggle.
• It follows docs/rfcs/README.md (header, Problem/Goals/Non-goals/Proposal/Open-questions/Rollout) and correctly frames itself as a design direction, deferring implementation-slice confirmation to Major UX regression: restore transparent chronological reasoning/tool-call stream in chat UI #3820.

The "one renderActivityEvent() across live / settled / reload" seam is the right structural insight, and the deterministic-first rollout (settled/reload PR before the subjective live-viewport PR) is sound.

Accepting accepts the direction only — per the RFC and the RFCs README, implementation slices still get confirmed in #3820 before any code PR. Thanks @franksong2702, this is a model RFC.