RFD 095: Reasoning-region shading across tool calls

• Status: Implemented
• Category: Design
• Authors: Jean Mertz git@jeanmertz.com
• Date: 2026-06-25
• Extends: RFD 048

Summary

When the assistant interleaves reasoning with tool calls, treat the tool calls as part of the surrounding reasoning region: extend the reasoning background across the tool chrome (header, arguments, progress, results) instead of letting the shading flip off for each tool call and back on for the next reasoning block. Shaded chrome preserves any background the tool's own output already carries. The behavior is configurable and defaults to on.

Motivation

With style.reasoning.background set, reasoning content renders with a full-width background fill that visually distinguishes it from the assistant's answer. Models with interleaved thinking (reasoning, then a tool call, then more reasoning, repeated) break this: each tool call drops the shading and the next reasoning block picks it back up, so the background flips on and off down the screen.

That flip portrays the wrong mental model. The model is reasoning, and calling tools while it reasons — not stopping its reasoning, doing unrelated work, and starting over. The visuals should portray one continuous reasoning region that happens to contain tool calls.

Doing nothing leaves the shading fragmented for exactly the models whose reasoning is most worth following.

Design

What the user sees

A reasoning region is a contiguous span of an assistant turn that begins at the first reasoning content and persists across any interleaved tool calls. It ends when the assistant emits ordinary message content (the answer) or the turn ends. The rule that decides membership is simple: a tool call belongs to the reasoning region when the immediately preceding chat response was reasoning.

Within a reasoning region, the configured reasoning background now also fills the tool chrome — the Calling tool … header, the argument preview, the progress line, and the inline result. The fill is applied as a default background: where the tool's own output already sets a background (a syntax theme, a sub-command that emits its own SGR), that background is preserved and the region fill is suppressed for those spans.

This applies only when reasoning produces persistent shaded content — the full and <number> (truncate) display modes. progress, static, and timer write ephemeral chrome with no shaded region to extend, so they are unaffected. summary is currently unimplemented; if it later renders persistent reasoning content, it should opt into the same rule in that follow-up.

Configuration

A new boolean under style.reasoning, defaulting to true:

[style.reasoning]
background = 236
# Extend the reasoning background across tool calls made while reasoning.
extend_across_tool_calls = true

The flag gates only the extension. With background unset there is no fill to extend, so the flag is a no-op; setting background and leaving the flag at its default produces the continuous region. Setting the flag to false restores the current per-block behavior.

Why this is non-trivial

Reasoning and tool chrome are rendered by two different components writing to two different channels (RFD 048):

• ChatRenderer writes reasoning and message content to stdout and owns the background fill, via jp_md's DefaultBackground / TerminalOptions.
• ToolRenderer writes the tool header, arguments, progress, and results to stderr with ad-hoc write!s and, before this RFD, had no background concept.

The two are siblings: in the live path turn_loop owns the TurnCoordinator (which owns ChatRenderer via TurnView) and the ToolRenderer separately; in replay TurnRenderer owns both. On an interleaved terminal — the common jp q … case — stdout and stderr display together, so the unshaded stderr chrome is the visible gap in an otherwise shaded region.

The redirect cases are already handled by the channel model: non-pretty output strips ANSI on both stdout and stderr, and --format auto resolves to non-pretty when stdout is not a terminal, so jp q > out 2> err never sees the fill on either stream. No new behavior is needed there.

The problem splits into two independent concerns.

The "when": region membership

The determining state is the kind of the last chat response (reasoning vs. message), which a tool call must read but must not overwrite. Before this RFD, the tool-call transition overwrote the only record that the region was reasoning. ChatRenderer now keeps a separate last_response_kind field that remembers the last chat-response kind across tool-call interludes.

Membership is decided per tool call, at the request boundary, and captured by tool-call ID — not held as a single renderer-wide flag. A tool call's header is rendered while streaming, but its result is rendered later, in the execution phase, where several tools' results are emitted in sequence after the stream has ended. By then the "current" region is meaningless, so the boundary captures the region background for that tool ID and the result rendering looks it up:

• Live: at ToolCallPart::Start (the enter_tool_call boundary), record the region background under the tool-call ID.
• Replay: TurnRenderer already keys tool_names: HashMap<id, name>; a parallel HashMap<id, Option<DefaultBackground>> captures the region when the ToolCallRequest is rendered and is consumed when the matching ToolCallResponse renders.

The boundary itself is an operation, not a passive query. A value read after the buffer flush would be too late, because the flush drains the deferred reasoning separator. So enter_tool_call decides shaded-vs-unshaded before draining, emits the separator accordingly (shaded when the region continues across the tool call, unshaded when reasoning gave way to a message), and returns the region background to the caller for the tool renderer.

A tool call is transparent to the region when it shows no chrome. Chrome is suppressed per-tool (style.hidden = true) and globally (style.tool_call.show = false, which hands the ToolRenderer a sink at turn_loop.rs:178); in the live path render_approved_tool and the result rendering also early-return on is_hidden (tool/coordinator.rs:658, :1079). All of these produce no chrome, so the boundary keys off a single predicate rather than the per-tool flag alone:

let tool_chrome_visible =
    cfg.style.tool_call.show && !printer.format().is_json() && !tool_style.hidden;

When tool_chrome_visible is false the boundary is transparent: it does not drain the pending reasoning separator, does not overwrite the last chat-response kind, and records no region metadata to shade. The separator decision defers to the next visible content, so an invisible tool between two reasoning blocks leaves the region intact. (In JSON mode the chat renderer is already a sink at turn/coordinator.rs:184, so the !is_json term only governs the tool renderer; chat spacing is moot there.)

The predicate is uniform across render paths: live and replay both answer is this tool's chrome visible? with show && !json && !hidden. Replay currently diverges: TurnRenderer builds the ToolRenderer with the real printer unconditionally (turn.rs:74-81, :193-199) and gates only on per-tool hidden (turn.rs:126, :128, :153), so jp conversation print ignores style.tool_call.show and the JSON format. That divergence is a bug, not a constraint to design around: the replay phase wires the same predicate into TurnRenderer, fixing it as part of delivering replay parity.

The live boundary runs once, owned by turn_loop. Before this RFD, the live path entered tool-call mode in two places — a redundant call from turn_loop and another from TurnCoordinator::handle_streaming_event for the same ToolCallPart::Start — harmless only because the operation was idempotent. Once the boundary drains the separator and captures per-ID region state it must run exactly once, so turn_loop owns it: it alone holds the tool id, name, cfg, and ToolRenderer needed to compute tool_chrome_visible and record region metadata by id. TurnCoordinator no longer fires the boundary on tool starts.

The "how": a shading invariant, enforced by a writer

Shading is not a line transform. The right model is a terminal background invariant: while a region with background B is active, every visual line shows B from column 0 to the right edge — including lines produced by cursor-relative rewrites (the \r-redrawn Calling tool … temp line and the ⏱ Running… progress line, which can stay on screen for tens of seconds) — except spans where the content sets its own background.

jp_md already enforces this invariant for markdown lines: AnsiState (ansi.rs) tracks the content's active background (48;…) and TerminalWriter applies a DefaultBackground, restoring it around spans that set their own. That logic is pub(crate) and welded to the wrap pipeline. This RFD lifts it into a reusable, stateful ShadedWriter decorator:

/// Wraps a writer and maintains a default-background invariant across the byte
/// stream, preserving any background the content sets itself.
/// The tracked `AnsiState` persists across writes.
pub struct ShadedWriter<W: Write> { /* … */ }

/// Convenience: run a `ShadedWriter` over a buffer.
/// Used by replay and tests; the live path uses the streaming decorator
/// directly.
pub fn shade(text: &str, background: &DefaultBackground) -> String;

ShadedWriter enforces, as bytes flow through:

• At each logical line start (stream start, after \n, after \r): assert B if no content background is active, so a following \x1b[K erases withB and following text sits on B.
• Before forwarding a content \x1b[K: assert B first only when no content background is active, so the erase fills with B; when the content has its own background, leave it so the erase preserves the content's fill.
• Before a \n: emit \x1b[K to fill to the right edge with the current background (the \x1b[{param}m\x1b[K\x1b[49m shape render_separator already uses).
• After content emits \x1b[0m or \x1b[49m: re-assert B so the region survives a content reset.
• When content sets its own 48;… background: suppress B for that span, restore on the content's bg-off (tracked by AnsiState).
• At region end: emit \x1b[49m so B does not leak past the region.

The state persists across writes for the same reason jp_printer's AnsiStripper persists its vte::Parser: a sequence or line boundary can split across write! calls. The pure shade function is a thin wrapper that runs the decorator over an owned buffer — one core, two surfaces.

The tool chrome is arbitrary text plus ANSI, not markdown — it must not be routed through the markdown formatter, which would parse # foo as a heading and * x as a bullet. The SGR-aware writer is the correct shared mechanism; the markdown parser is not.

ToolRenderer activates a ShadedWriter around the writes for a given tool when that tool's captured region background is Some, and writes straight to err_writer() otherwise. Its existing write!/writeln! sites — header, argument preview, the \r-rewritten temp/progress line, the \r\x1b[K clear on completion, and the result — flow through unchanged; the decorator does the work. Tool-result code blocks already pass through the formatter's render_code_line, so they take the background param directly. The temp/progress line is a live aggregate of the tools pending now, so it uses the currently-active region; each tool's permanent header and result use that tool's captured region.

ShadedWriter contract

The writer acts on two escape families — SGR (\x1b[…m) and the CSI erase \x1b[K. Any other escape is forwarded verbatim and does not affect the invariant; a malformed or split sequence is held by the persistent parser until it completes, as AnsiStripper already does. "Forwarded verbatim" requires recognizing each escape as a whole unit: OSC string sequences (\x1b]… terminated by BEL or ST) — most importantly the OSC 8 hyperlinks a tool result emits — must be tokenized end-to-end so they pass through intact while their visible link text is still shaded. The tokenizer cannot stop an OSC at the first letter the way it does for a CSI sequence.

It parses compound SGR parameters, not only standalone \x1b[48;…m. Real tool output combines attributes — \x1b[1;48;5;236m, \x1b[38;2;…;48;2;…m, \x1b[0;48;5;236m, \x1b[39;49m — and a writer that matched only a leading 48; would miss the content's background and shade over it. Before this RFD, AnsiState matched a leading 48;/38; only; phase 2 extends it to scan each ;-separated sub-parameter for 48/49/38/39.

Erase policy: a content \x1b[K fills with the content's background when one is active, and with the region background otherwise — so a tool that sets its own background and clears to end-of-line keeps its own fill, and the region background only backs spans the content left at default. The writer emits \x1b[49m at region end so B never leaks past it.

Data flow

reasoning chunk ─▶ ChatRenderer (stdout, shaded)
                     │ remembers: last chat response = Reasoning
                     ▼
tool A start    ─▶ enter_tool_call: shade pending separator, return Some(bg)
                     │ capture region[A] = Some(bg)
                     ▼
                  ToolRenderer: A's writes go through ShadedWriter(bg)
                     │ header / args / temp+progress line / result
                     ▼ (stderr, shaded; content's own bg preserved)
reasoning chunk ─▶ ChatRenderer (stdout, shaded; region continues)
message chunk  ─▶ ChatRenderer (stdout, unshaded; region ends)
tool B start    ─▶ capture region[B] = None  (followed a message)
                     ▼ B's result later renders unshaded; A's stays shaded

Drawbacks

• Shading stderr chrome with the reasoning background couples the chrome channel to an assistant-output styling decision. The split-redirect case (jp q 2> err with stdout a TTY) carries the fill onto the redirected stderr — but that stream already carries chrome ANSI (yellow tool names) today, so the coupling is pre-existing, not introduced here.
• The region decision lives in ChatRenderer while the per-tool-call-ID capture and application live in ToolRenderer, and both have to stay consistent across the live and replay paths.
• Exposing ShadedWriter widens jp_md's public API (Hyrum's Law) for a capability that previously had a single internal caller; its background invariant becomes an observable contract.

Alternatives

• Shared shading context lifted to the coordinator. A single ShadingState owned by turn_loop / TurnRenderer, threaded into both renderers. This is the cleaner single-source-of-truth shape, but the region decision still originates in ChatRenderer's content-kind tracking, and the threading is more than one consumer justifies today. Revisit if a third consumer of the region appears (e.g. structured output or inquiry chrome).
• Route chrome through the markdown formatter. Rejected: tool output and argument previews are not markdown; parsing them would mangle their content. Only the SGR-aware background primitive is worth sharing.
• Shade permanent chrome only; leave the progress/temp line unshaded. Rejected: a streaming tool call holds the \r-redrawn line on screen for tens of seconds, so this leaves the longest-lived unshaded gap in the region — exactly the flicker the feature exists to remove.
• A pure line-oriented shade_lines(&str). Rejected: it cannot maintain the background across \r/\x1b[K cursor rewrites, which is precisely the progress/temp-line case. The invariant has to be enforced across the byte stream, which is what ShadedWriter does; a pure shade over a buffer stays available as a convenience built on the same core.

Non-Goals

• Changing the reasoning display modes or the meaning of style.reasoning.background.
• Per-stream ANSI policy on redirect — already handled by the four-channel model.
• Shading non-reasoning regions, or shading tool calls that follow ordinary message content.

Risks and Open Questions

• Ordering. The shaded stderr lines only abut the shaded stdout lines because the Printer serializes both streams through one command channel. The implementation must not break that serialization.
• Replay parity. Both paths apply the same tool_chrome_visible predicate. Because replay today ignores show/json (a bug), wiring the predicate into TurnRenderer is a user-visible fix in its own right: transcripts printed with style.tool_call.show = false stop rendering tool chrome. Call that out in the change log when the replay phase lands.
• Region end semantics. The rule ends the region at the first message content. A model that emits message text between reasoning and a tool call ends the region early; this is the intended reading of "the previous chat response was reasoning," implemented as last_response_kind tracking in ChatRenderer.
• Concurrent tools in one region. The temp line aggregates all pending tools and uses the current region; per-tool permanent output uses each tool's captured region. If two tools were registered under different regions (a message arrived between them), the shared temp line reflects the current one — acceptable, since it is inherently a live aggregate.
• Shared AnsiState. Extending AnsiState to parse compound SGR changes a type the markdown code path already uses for background restoration. Cover it with characterization tests on current markdown rendering before the change, to avoid a silent regression there.
• Overlap with RFD 084. RFD 084 (Discussion) migrates DefaultBackground::param from a pre-built SGR string to a logical Color built inside jp_md. Not a blocker, but if RFD 084 lands first, ShadedWriter should take the post-084 type; if this RFD lands first, RFD 084 must include the new public surface in its migration.

Implementation Plan

1. Region memory and a single live boundary. Track the last chat-response kind in ChatRenderer separately from last_content_kind. Make the tool-call boundary one operation owned by turn_loop, driven by a tool_chrome_visible predicate (show && !json && !hidden): when visible it decides the separator's shading before flushing and returns the region background; when not, it leaves the separator pending and captures nothing. Remove the duplicate enter_tool_call call from TurnCoordinator::handle_streaming_event. Unit-testable; mergeable on its own (no visible change until the chrome consumes it).
2. ShadedWriter in jp_md. Lift the background-invariant logic out of TerminalWriter into a public stateful decorator plus a shade convenience, and extend AnsiState to parse compound SGR parameters. Tests cover \r/\x1b[K rewrites, compound-SGR content backgrounds, erase-under-content-background, and resets mid-stream; add characterization coverage on the existing markdown code path first. Mergeable independently.
3. OSC-aware tokenization for shaded hyperlinks. Teach the shared segments tokenizer (and ShadedWriter's split-escape detection) to recognize OSC string sequences (\x1b]… terminated by \x07 or \x1b\\) as whole escapes, so a tool result's OSC 8 hyperlinks pass through ShadedWriter verbatim while their visible link text is still shaded. Without it the line-oriented tokenizer stops an OSC at its first letter and the writer injects the region background into the middle of the URL, corrupting the link. Tests cover an OSC 8 hyperlink under shading, an OSC split across writes, and a segments/visual_width round-trip on OSC. Mergeable independently; a prerequisite for routing results through ShadedWriter in the next phase.
4. Per-ID chrome shading in ToolRenderer. Capture the region background by tool-call ID at the request boundary; route that tool's writes — the whole result included — through a ShadedWriter when set. render_code_line keeps passing None; the writer is the sole owner of the result's background. Depends on phases 1, 2, and 3.
5. Config field. Add style.reasoning.extend_across_tool_calls (bool, default true); it lives alongside style.reasoning.background and is inert when that is unset. Gates phase 4.
6. Replay path. Capture the per-ID region in TurnRenderer and apply the same tool_chrome_visible predicate as live — this fixes the pre-existing bug that replay ignores style.tool_call.show and JSON. Verify the shaded replay output via snapshot tests.

References

• RFD 048 — Four-Channel Output Model (stdout/stderr/tty/log split).
• crates/jp_cli/src/render/chat.rs — reasoning background, content-kind tracking, deferred separator.
• crates/jp_cli/src/render/tool.rs — tool chrome rendering.
• crates/jp_md/src/shade.rs — the ShadedWriter decorator and shade.
• crates/jp_md/src/writer.rs, crates/jp_md/src/ansi.rs — DefaultBackground application and AnsiState background tracking.
• crates/jp_config/src/style/reasoning.rs — reasoning style config.