@cruxy/cli 0.7.0 → 0.8.0

package/README.md

@@ -58,6 +58,12 @@ export CRUXY_API_KEY=cxy_live_...   # …or just use an env var (always wins)
   validated, and never auto-executed.
 - **Agent** — streaming output, multi-turn interactive sessions, context
   compaction, and awareness of git state and project instructions (`CRUXY.md`).
+- **Streaming render** — flicker-free live output: a single in-place status line
+  (spinner while the model thinks / tools run), append-only committed text,
+  syntax-highlighted code fences, tool-call notes, and diffs drawn by the same
+  renderer as the approval prompt. Degrades cleanly: piped/CI output is plain
+  append-only text with zero ANSI (chrome on stderr), `NO_COLOR` drops color,
+  and `CRUXY_NO_SPINNER=1` stills the animation.
 - **Plan mode** (opt-in: `cruxy run --plan`, `/plan`, or `agent.planMode`) — the
   agent proposes a structured, step-by-step plan; you approve it once, then it
   executes with live per-step status. Approving consents to the _shape_ of the

package/dist/agent/loop.d.ts

@@ -1,5 +1,6 @@
 import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
+import type { StreamRenderer } from "../render/index.js";
 import type { ToolContext } from "../tools/index.js";
 import { ToolRegistry } from "../tools/index.js";
 export interface RunAgentArgs {
@@ -17,12 +18,13 @@ export interface RunAgentArgs {
     /** Ambient capabilities handed to each tool. */
     ctx: ToolContext;
     /**
-     * Optional sink for assistant text as it streams: called per text delta, then
-     * once with a lone "\n" to close each non-empty text segment on its own line.
-     * When set, `runAgent` streams live and does not buffer-print the turn (the
-     * caller renders); when omitted, behavior is unchanged (one buffered print).
+     * The render seam (U.2): assistant text streams through `renderer.write`
+     * delta by delta (each non-empty segment closed via `endSegment`), and
+     * tool-call progress is surfaced as transient `status` + committed `note`
+     * lines. When omitted, behavior is unchanged (one buffered print per turn,
+     * no tool-call chrome). The loop never touches stdout directly.
      */
-    onText?: (delta: string) => void;
+    renderer?: StreamRenderer;
     /** Git context (branch + dirty) for the system prompt's Environment section. */
     git?: {
         branch: string;

package/dist/agent/loop.js

@@ -10,10 +10,23 @@ import { buildSystemPrompt } from "./prompts.js";
  * silently running tool-less.
  */
 export async function runAgent(args) {
-    const { provider, registry, config, ctx } = args;
+    const { provider, config, renderer } = args;
     if (!provider.supportsTools) {
         throw providerUnsupported(config.model.provider);
     }
+    renderer?.beginTurn();
+    try {
+        return await driveLoop(args, renderer);
+    }
+    finally {
+        // Always leave the terminal clean: no orphaned status line, no held text —
+        // even when a provider error aborts the turn mid-stream.
+        renderer?.endTurn();
+    }
+}
+/** The body of {@link runAgent}, split out so turn cleanup lives in one finally. */
+async function driveLoop(args, renderer) {
+    const { provider, registry, config, ctx } = args;
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the
     // extended history is returned for the caller to adopt.
@@ -42,6 +55,8 @@ export async function runAgent(args) {
         let turnText = "";
         const pending = new Map();
         const toolUses = [];
+        // Live progress while waiting on the model; dismissed by the first delta.
+        renderer?.status("thinking…");
         for await (const ev of provider.stream({
             system,
             messages,
@@ -50,7 +65,7 @@ export async function runAgent(args) {
             switch (ev.type) {
                 case "text_delta":
                     turnText += ev.text;
-                    args.onText?.(ev.text);
+                    renderer?.write(ev.text);
                     break;
                 case "tool_use_start":
                     pending.set(ev.index, { id: ev.id, name: ev.name });
@@ -83,13 +98,13 @@ export async function runAgent(args) {
         }
         // ── Record the assistant turn ───────────────────────────────────────────
         if (turnText) {
-            // Streaming (onText set): the text already reached the user delta by delta,
-            // so close the segment with a single newline through the *same* sink — no
-            // separate buffered print racing the stream — so tool output, the next
-            // turn, or an approval prompt starts on its own line. Otherwise render the
-            // whole buffered block (no-callback path, unchanged).
-            if (args.onText)
-                args.onText("\n");
+            // Streaming (renderer set): the text already reached the user delta by
+            // delta, so close the segment through the *same* renderer — it flushes any
+            // held partial line and terminates with one newline, so tool output, the
+            // next turn, or an approval prompt starts on its own line. Otherwise
+            // render the whole buffered block (no-renderer path, unchanged).
+            if (renderer)
+                renderer.endSegment();
             else
                 logger.print(turnText);
         }
@@ -105,13 +120,40 @@ export async function runAgent(args) {
         // ── Execute each tool call, collecting one tool_result per call ──────────
         const toolResults = [];
         for (const call of toolUses) {
-            toolResults.push(await runToolCall(call, registry, ctx));
+            const label = describeToolCall(call);
+            renderer?.status(`${label}…`);
+            const result = await runToolCall(call, registry, ctx);
+            renderer?.note(`${result.is_error ? "✗" : "✓"} ${label}`);
+            toolResults.push(result);
         }
         messages.push({ role: "user", content: toolResults });
     }
     logger.warn(`reached maxIterations (${maxIterations}) without completing`);
     return { messages, iterations, stop: "max_iterations", usage };
 }
+/** Input keys worth surfacing in tool-call chrome, in preference order. */
+const HINT_KEYS = ["path", "file_path", "command", "pattern", "query", "url"];
+/** Longest hint shown before truncation — chrome, not information of record. */
+const HINT_MAX = 60;
+/**
+ * A short human label for a tool call ("read_file src/x.ts"): the tool name
+ * plus the first recognizable scalar argument, if any. Best-effort — unknown
+ * shapes fall back to the bare name.
+ */
+function describeToolCall(call) {
+    const input = call.input;
+    if (typeof input === "object" && input !== null) {
+        for (const key of HINT_KEYS) {
+            const value = input[key];
+            if (typeof value === "string" && value !== "") {
+                const flat = value.replace(/\s+/g, " ").trim();
+                const hint = flat.length > HINT_MAX ? flat.slice(0, HINT_MAX - 1) + "…" : flat;
+                return `${call.name} ${hint}`;
+            }
+        }
+    }
+    return call.name;
+}
 /**
  * Dispatch a single reassembled tool call to its tool and shape the outcome as
  * a `tool_result` block. Unknown tools and invalid arguments become `is_error`

package/dist/agent/session.d.ts

@@ -1,5 +1,6 @@
 import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
+import type { StreamRenderer } from "../render/index.js";
 import type { ToolContext } from "../tools/index.js";
 import type { ToolRegistry } from "../tools/index.js";
 import { type AgentResult } from "./loop.js";
@@ -12,7 +13,7 @@ import { type AgentResult } from "./loop.js";
 export type PlanRunner = (args: {
     messages: Message[];
     projectInstructions: string | null;
-    onText?: (delta: string) => void;
+    renderer?: StreamRenderer;
 }) => Promise<AgentResult>;
 export interface SessionArgs {
     /** A constructed provider to stream from. */
@@ -76,10 +77,11 @@ export declare class Session {
      * the threshold, drive the agent loop over the full history, adopt the
      * extended history, and accumulate usage. Returns the turn's `AgentResult`.
      *
-     * `onText`, when supplied, receives assistant text deltas as they stream so the
-     * caller can render them live (see the REPL); history is unaffected.
+     * `renderer`, when supplied, receives assistant text deltas and tool-call
+     * progress as they stream so the caller sees the turn live (see the REPL);
+     * history is unaffected.
      */
-    send(userPrompt: string, onText?: (delta: string) => void): Promise<AgentResult>;
+    send(userPrompt: string, renderer?: StreamRenderer): Promise<AgentResult>;
     /**
      * Re-read project instructions (CRUXY.md / AGENTS.md) from the working
      * directory so edits take effect without restarting. Returns the new text, or

package/dist/agent/session.js

@@ -74,10 +74,11 @@ export class Session {
      * the threshold, drive the agent loop over the full history, adopt the
      * extended history, and accumulate usage. Returns the turn's `AgentResult`.
      *
-     * `onText`, when supplied, receives assistant text deltas as they stream so the
-     * caller can render them live (see the REPL); history is unaffected.
+     * `renderer`, when supplied, receives assistant text deltas and tool-call
+     * progress as they stream so the caller sees the turn live (see the REPL);
+     * history is unaffected.
      */
-    async send(userPrompt, onText) {
+    async send(userPrompt, renderer) {
         this.messages.push({ role: "user", content: userPrompt });
         // Compact *before* the agent call so the turn runs against a bounded history.
         await this.maybeCompact();
@@ -88,7 +89,7 @@ export class Session {
             ? await this.args.planRunner({
                 messages: this.messages,
                 projectInstructions: this.projectInstructions,
-                onText,
+                renderer,
             })
             : await runAgent({
                 messages: this.messages,
@@ -96,7 +97,7 @@ export class Session {
                 // After the spread so a mid-session `/reload` wins over the initial value.
                 projectInstructions: this.projectInstructions,
                 planMode: false, // the plan directive belongs only to the runner's propose phase
-                onText,
+                renderer,
             });
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;

package/dist/approval/prompt.d.ts

@@ -1,4 +1,13 @@
 import type { ApprovalRequest } from "./types.js";
+/**
+ * The interactive prompt: render a pending action (a real diff for file edits,
+ * the exact command + cwd for shell) and read a 4-way choice. Rendering is data
+ * → string so it's testable; color is gated on `io.color` (NO_COLOR / non-TTY
+ * aware). **Default-deny**: EOF / Ctrl-C / any unrecognized key → reject.
+ *
+ * Diff/preview rendering is the shared implementation in `render/diff.ts` —
+ * the streaming path and this prompt draw the same bytes for the same change.
+ */
 /** The four user choices (plus the implicit default-deny). */
 export type PromptChoice = {
     kind: "once";

package/dist/approval/prompt.js

@@ -1,7 +1,6 @@
 import path from "node:path";
 import pc from "picocolors";
-/** Cap on rendered preview lines before collapsing the rest. */
-const PREVIEW_MAX_LINES = 40;
+import { renderActionPreview } from "../render/diff.js";
 /**
  * Render the action, read one key, and map it to a {@link PromptChoice}. `n`/`t`
  * read a follow-up line (reason / instruction). Anything else — including EOF —
@@ -53,7 +52,7 @@ function detail(request, c) {
             `  ${c.dim(`in ${request.cwd}`)}`,
         ].join("\n");
     }
-    return renderPreview(request.action.preview, c);
+    return renderActionPreview(request.action.preview, c);
 }
 /** The choices line, including a short label of what an `a` grant would cover. */
 function choices(scope, c) {
@@ -71,80 +70,6 @@ function scopeLabel(scope) {
         return `changes under ${path.basename(scope.root)}/`;
     return null;
 }
-// ── diff rendering (shared with the old C.6 renderer) ──────────────────────────
-function diffLines(oldStr, newStr, c) {
-    const removed = oldStr.split("\n").map((l) => c.red(`- ${l}`));
-    const added = newStr.split("\n").map((l) => c.green(`+ ${l}`));
-    return [...removed, ...added];
-}
-function renderPatchFiles(files, c) {
-    const out = [];
-    for (const file of files) {
-        if (file.op === "delete") {
-            out.push(c.red(`delete ${file.path}`));
-        }
-        else if (file.op === "create") {
-            out.push(c.green(`create ${file.path}`));
-            out.push(...file.lines.map((l) => c.green(`+ ${l}`)));
-            if (file.omittedLines > 0)
-                out.push(c.dim(`  ...${file.omittedLines} more lines`));
-        }
-        else {
-            out.push(c.yellow(`update ${file.path}`));
-            for (const hunk of file.hunks)
-                out.push(...diffLines(hunk.oldStr, hunk.newStr, c));
-        }
-    }
-    return out;
-}
-/** Render a `vcs` pull-request publish plan: branch, commit, and PR body. */
-function renderPrPreview(preview, c) {
-    const out = [];
-    out.push(`${c.bold("branch")}  ${c.green(preview.branch)} → ${preview.base}`);
-    out.push("");
-    out.push(c.bold("commit"));
-    out.push(`  ${preview.commitSubject}`);
-    for (const line of bodyLines(preview.commitBody))
-        out.push(c.dim(`  ${line}`));
-    out.push("");
-    out.push(`${c.bold("pull request")}  ${preview.prTitle}`);
-    for (const line of bodyLines(preview.prBody))
-        out.push(c.dim(`  ${line}`));
-    return out;
-}
-/** Split a multi-line body into trimmed-of-trailing lines, dropping a trailing blank. */
-function bodyLines(body) {
-    const lines = body.replace(/\s+$/, "").split("\n");
-    return lines.length === 1 && lines[0] === "" ? [] : lines;
-}
-function renderPreview(preview, c) {
-    if (!preview)
-        return "";
-    let lines;
-    if (preview.type === "edit") {
-        lines = diffLines(preview.oldStr, preview.newStr, c);
-    }
-    else if (preview.type === "patch") {
-        lines = renderPatchFiles(preview.files, c);
-    }
-    else if (preview.type === "pr") {
-        lines = renderPrPreview(preview, c);
-    }
-    else {
-        const header = preview.exists
-            ? c.yellow("OVERWRITE existing")
-            : c.green("create");
-        const body = preview.lines.map((l) => `  ${l}`);
-        if (preview.omittedLines > 0)
-            body.push(c.dim(`  ...${preview.omittedLines} more lines`));
-        lines = [header, ...body];
-    }
-    if (lines.length > PREVIEW_MAX_LINES) {
-        const hidden = lines.length - PREVIEW_MAX_LINES;
-        lines = [...lines.slice(0, PREVIEW_MAX_LINES), c.dim(`...${hidden} more`)];
-    }
-    return lines.map((l) => `  ${l}`).join("\n");
-}
 // ── default stdin-backed PromptIO ──────────────────────────────────────────────
 /** Build the real PromptIO: prompt to stderr, read keys/lines from stdin. */
 export function defaultPromptIO(color) {

package/dist/cli/commands/run.js

@@ -3,8 +3,8 @@ import pc from "picocolors";
 import { logger } from "../../utils/logger.js";
 import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { authMissingKey, usageError } from "../../errors/index.js";
+import { createRenderer } from "../../render/index.js";
 import { runInteractive } from "../repl.js";
-import { createStreamPrinter } from "../stream-print.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 export function runCommand() {
@@ -50,22 +50,28 @@ export function runCommand() {
         }
         // Plan mode is opt-in: --plan flag overrides the config default.
         const planMode = opts.plan ?? config.agent.planMode;
-        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode);
+        // One renderer for the whole run (U.2): the streaming path and the
+        // approval prompt's status-suspend hook must share the same live region.
+        const renderer = createRenderer();
+        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer);
         if (interactive) {
-            await runInteractive(session);
+            await runInteractive(session, undefined, renderer);
             return;
         }
         // One-shot: a single turn, then exit. Preserves scripting/pipe use.
-        // Assistant text streams to stdout delta by delta (same as the REPL),
-        // through a printer that trims the model's leading blank lines; the agent
-        // loop terminates the line.
+        // Assistant text streams to stdout delta by delta (same as the REPL);
+        // piped output degrades to the plain renderer (no ANSI, chrome on stderr).
         logger.print(`${pc.cyan("cruxy")} ${pc.dim("›")} ${prompt}\n`);
         // Provider/network/auth failures propagate to the top-level boundary,
         // which classifies them (e.g. CRUXY_E_GATEWAY_UNREACHABLE) and exits with
         // the matching code — a one-shot run must fail non-zero on error.
-        const print = createStreamPrinter((text) => process.stdout.write(text));
-        const result = await session.send(prompt, print);
-        logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
-            `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
+        try {
+            const result = await session.send(prompt, renderer);
+            logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
+                `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
+        }
+        finally {
+            renderer.close();
+        }
     });
 }

package/dist/cli/onboard.js

@@ -1,6 +1,6 @@
 import { resolveApiKey } from "../config/index.js";
 import { createDefaultDeps, defaultOnboardingIO, isFirstRun, runOnboarding, } from "../onboarding/index.js";
-import { createStreamPrinter } from "./stream-print.js";
+import { createRenderer } from "../render/index.js";
 import { buildAgentSession } from "./session-factory.js";
 /**
  * CLI-layer glue between the entry points and the onboarding module (U.6). Keeps
@@ -23,9 +23,14 @@ export async function runFirstWinTask(config, cwd, prompt) {
     const apiKey = resolveApiKey(config.model.provider);
     if (!apiKey)
         return; // defensive — the key was just persisted
-    const session = buildAgentSession(config, apiKey, cwd, true);
-    const print = createStreamPrinter((text) => process.stdout.write(text));
-    await session.send(prompt, print);
+    const renderer = createRenderer();
+    const session = buildAgentSession(config, apiKey, cwd, true, false, renderer);
+    try {
+        await session.send(prompt, renderer);
+    }
+    finally {
+        renderer.close();
+    }
 }
 /**
  * Run the guided first-run flow **iff** this is a first run; otherwise return

package/dist/cli/repl.d.ts

@@ -1,5 +1,6 @@
 import type { Readable, Writable } from "node:stream";
 import type { Session } from "../agent/index.js";
+import { type StreamRenderer } from "../render/index.js";
 /** The stdin/stdout pair the REPL reads from and prompts on. Injectable for tests. */
 export interface ReplIO {
     input: Readable;
@@ -7,9 +8,13 @@ export interface ReplIO {
 }
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
- * commands or run a turn, repeat. Assistant text streams to stdout from within
- * `session.send` (via the logger); this loop only owns input and control.
+ * commands or run a turn, repeat. Assistant text and tool-call progress stream
+ * through the `renderer` from within `session.send`; this loop only owns input
+ * and control.
  *
- * `io` defaults to real stdin/stdout; tests inject a scripted stream pair.
+ * `io` defaults to real stdin/stdout; tests inject a scripted stream pair. The
+ * renderer defaults to whatever `io.output` supports (a TTY gets the managed
+ * live region, anything else the plain append-only renderer); `cruxy run`
+ * passes its own so the approval prompt's status-suspend hook shares it.
  */
-export declare function runInteractive(session: Session, io?: ReplIO): Promise<void>;
+export declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer): Promise<void>;

package/dist/cli/repl.js

@@ -1,8 +1,8 @@
 import readline from "node:readline";
 import pc from "picocolors";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
+import { createRenderer } from "../render/index.js";
 import { logger } from "../utils/logger.js";
-import { createStreamPrinter } from "./stream-print.js";
 const PROMPT = `${pc.cyan("cruxy")} ${pc.dim("›")} `;
 const HELP = `Commands:
   /help          show this help
@@ -65,13 +65,25 @@ function printReplError(err) {
 }
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
- * commands or run a turn, repeat. Assistant text streams to stdout from within
- * `session.send` (via the logger); this loop only owns input and control.
+ * commands or run a turn, repeat. Assistant text and tool-call progress stream
+ * through the `renderer` from within `session.send`; this loop only owns input
+ * and control.
  *
- * `io` defaults to real stdin/stdout; tests inject a scripted stream pair.
+ * `io` defaults to real stdin/stdout; tests inject a scripted stream pair. The
+ * renderer defaults to whatever `io.output` supports (a TTY gets the managed
+ * live region, anything else the plain append-only renderer); `cruxy run`
+ * passes its own so the approval prompt's status-suspend hook shares it.
  */
-export async function runInteractive(session, io = defaultIO()) {
+export async function runInteractive(session, io = defaultIO(), renderer = createRenderer(io.output, process.stderr)) {
     logger.print(pc.dim("interactive session — /help for commands, /exit or Ctrl+D to quit"));
+    try {
+        await replLoop(session, io, renderer);
+    }
+    finally {
+        renderer.close();
+    }
+}
+async function replLoop(session, io, renderer) {
     for (;;) {
         const line = await readLine(io, PROMPT);
         // EOF / Ctrl+D.
@@ -120,14 +132,13 @@ export async function runInteractive(session, io = defaultIO()) {
             logger.print(HELP);
             continue;
         }
-        // A real turn. Assistant text streams to the output delta by delta through a
-        // single printer (which trims the model's leading blank lines); the agent
-        // loop closes the segment with one newline, so the next prompt lands on its
-        // own line. Errors (provider/API failures) log and return to the prompt
-        // rather than killing the REPL.
+        // A real turn. Assistant text streams through the renderer delta by delta
+        // (leading blank lines trimmed, code fences highlighted); the agent loop
+        // closes each segment with one newline, so the next prompt lands on its own
+        // line. Errors (provider/API failures) log and return to the prompt rather
+        // than killing the REPL.
         try {
-            const print = createStreamPrinter((text) => io.output.write(text));
-            await session.send(line, print);
+            await session.send(line, renderer);
         }
         catch (err) {
             logger.error(err.message);

package/dist/cli/session-factory.d.ts

@@ -1,4 +1,5 @@
 import type { CruxyConfig } from "../config/index.js";
+import type { StreamRenderer } from "../render/index.js";
 import { Session } from "../agent/index.js";
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
@@ -9,4 +10,4 @@ import { Session } from "../agent/index.js";
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean): Session;
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer): Session;

package/dist/cli/session-factory.js

@@ -7,6 +7,23 @@ import { shouldUseColor } from "../errors/index.js";
 import { buildDefaultRegistry } from "../tools/index.js";
 import { Session } from "../agent/index.js";
 import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
+/**
+ * Wrap a PromptIO so the renderer's transient status line is erased before any
+ * prompt text lands (U.2): the approval prompt writes to stderr while the
+ * spinner owns the last stdout row of the same terminal — clearing first keeps
+ * the prompt from tearing through the live region.
+ */
+function suspendStatusOnPrompt(io, renderer) {
+    if (!renderer)
+        return io;
+    return {
+        ...io,
+        write: (text) => {
+            renderer.status(null);
+            io.write(text);
+        },
+    };
+}
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
  * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
@@ -16,7 +33,7 @@ import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false) {
+export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer) {
     const provider = createProvider({
         provider: config.model.provider,
         apiKey,
@@ -31,7 +48,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
     if (planMode) {
         // One io + allowlist shared by the plan-approval prompt and the per-action
         // gate, so a grant recorded during execution is honored by U.3's own check.
-        const io = defaultPromptIO(shouldUseColor());
+        const io = suspendStatusOnPrompt(defaultPromptIO(shouldUseColor()), renderer);
         const allowlist = new SessionAllowlist();
         const planPolicy = new PlanExecutionPolicy(allowlist, new InteractivePolicy(allowlist, io));
         const approval = new ApprovalService({
@@ -46,7 +63,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             logger,
             requestApproval: (action) => approval.requestApproval(action),
         };
-        const planRunner = ({ messages, projectInstructions, onText, }) => runPlanSession({
+        const planRunner = ({ messages, projectInstructions, renderer: turnRenderer, }) => runPlanSession({
             provider,
             config,
             ctx,
@@ -57,7 +74,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             messages,
             git,
             projectInstructions,
-            onText,
+            renderer: turnRenderer,
         });
         return new Session({
             provider,
@@ -70,7 +87,11 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             planRunner,
         });
     }
-    const approval = new ApprovalService({ cwd, interactive: ttyInteractive });
+    const approval = new ApprovalService({
+        cwd,
+        interactive: ttyInteractive,
+        io: suspendStatusOnPrompt(defaultPromptIO(shouldUseColor()), renderer),
+    });
     const ctx = {
         cwd,
         config,

package/dist/plan/service.d.ts

@@ -3,6 +3,7 @@ import type { CruxyConfig } from "../config/index.js";
 import type { PromptIO } from "../approval/index.js";
 import { ToolRegistry, type ToolContext } from "../tools/index.js";
 import { type AgentResult } from "../agent/loop.js";
+import type { StreamRenderer } from "../render/index.js";
 import { PlanExecutionPolicy } from "./policy.js";
 /**
  * Orchestrates a plan-mode turn (C.31): propose → approve/revise (capped) →
@@ -32,7 +33,7 @@ export interface PlanSessionArgs {
         dirty: boolean;
     } | null;
     projectInstructions?: string | null;
-    onText?: (delta: string) => void;
+    renderer?: StreamRenderer;
     /** Revision cap (defaults to {@link MAX_PLAN_REVISIONS}). */
     maxRevisions?: number;
 }

package/dist/plan/service.js

@@ -73,7 +73,7 @@ export async function runPlanSession(args) {
             ctx: args.ctx,
             git: args.git,
             projectInstructions: args.projectInstructions,
-            onText: args.onText,
+            renderer: args.renderer,
             planMode: true,
         }));
         if (!holder.plan) {
@@ -105,7 +105,7 @@ export async function runPlanSession(args) {
                     ctx: args.ctx,
                     git: args.git,
                     projectInstructions: args.projectInstructions,
-                    onText: args.onText,
+                    renderer: args.renderer,
                 }));
             };
             await executePlan(plan, { runStep, io: args.io });

package/dist/render/capabilities.d.ts

@@ -0,0 +1,12 @@
+import type { RenderCapabilities, RenderStream } from "./types.js";
+/**
+ * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
+ * given its inputs (stream + env are injectable), so every row of the
+ * degradation matrix is directly testable.
+ *
+ * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
+ * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
+ * Cursor control and color are independent axes — a NO_COLOR terminal still
+ * supports in-place status updates; a dumb terminal supports neither.
+ */
+export declare function detectCapabilities(stream?: RenderStream, env?: NodeJS.ProcessEnv): RenderCapabilities;

package/dist/render/capabilities.js

@@ -0,0 +1,27 @@
+import { shouldUseColor } from "../errors/index.js";
+/**
+ * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
+ * given its inputs (stream + env are injectable), so every row of the
+ * degradation matrix is directly testable.
+ *
+ * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
+ * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
+ * Cursor control and color are independent axes — a NO_COLOR terminal still
+ * supports in-place status updates; a dumb terminal supports neither.
+ */
+export function detectCapabilities(stream = process.stdout, env = process.env) {
+    const tty = Boolean(stream.isTTY);
+    const dumb = env.TERM === "dumb";
+    const cursor = tty && !dumb;
+    return {
+        tty,
+        color: shouldUseColor(stream, env) && !dumb,
+        cursor,
+        // Same set-and-non-empty convention as NO_COLOR: any value disables.
+        spinner: cursor &&
+            !(env.CRUXY_NO_SPINNER !== undefined && env.CRUXY_NO_SPINNER !== ""),
+        width: typeof stream.columns === "number" && stream.columns > 0
+            ? stream.columns
+            : 80,
+    };
+}