[Feature]: Explain pending approval commands in plain English

[Kawixh]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/web

Problem or use case

When T3 Code asks me to approve a command, the approval UI shows the raw shell command but does not explain what it is expected to do.

For simple commands this is fine, but many approval requests contain long absolute paths, scripts, package-manager commands, shell pipelines, or unfamiliar flags. I often have to mentally parse the command or inspect the referenced script before deciding whether to approve it.

The composer area below the approval panel currently repeats the raw command as its placeholder. That space could instead provide a short plain-English explanation of the command while keeping the original command visible above.

Proposed solution

When a command approval request appears, asynchronously generate a short plain-English explanation of the command and display it in the composer area below the approval panel.

The approval itself should appear immediately and must never wait for text generation.

Suggested behavior:

1. Show the existing approval panel and raw command immediately.

2. Replace the duplicated command placeholder in the composer area with a lightweight loading state such as:

   "Explaining this command..." OR "Generating explaination..."

3. In parallel, generate a 1–2 sentence explanation using T3 Code's existing text-generation workflow.

4. Use the model already selected under Settings -> Text generation model, including its configured reasoning level, rather than hardcoding a particular model or adding a new approval-specific model setting.

5. Replace the loading state with the generated explanation when it completes.

6. Keep Cancel turn, Decline, Always allow this session, and Approve once usable for the entire time.

7. If explanation generation fails or is unavailable, fall back gracefully to something like:

   “Review the command above before approving.”

The raw command should remain visible and authoritative. The generated explanation is informational only.

Example:

Command:
/Users/user/.volta/bin/node scripts/rename.mjs

Explanation:
“Runs the project's renaming script using Node.js. The exact changes depend on what the script implements.”

The explanation should avoid guessing when the command alone does not provide enough information.

Why this matters

Command approval is a safety boundary, so the UI should help users understand what they are authorizing rather than requiring them to interpret shell syntax themselves.

A short explanation would make approval prompts easier and faster to evaluate, especially for project-specific scripts, package-manager commands, long paths, pipelines, and unfamiliar flags.

It also makes better use of the composer area, which currently duplicates the same raw command already displayed above.

Reusing the existing Text generation model setting keeps this behavior consistent with other lightweight generated text in T3 Code and respects the user's existing model and reasoning preferences.

Smallest useful scope

A first version only needs to support command approvals.

When a command approval becomes active:

• Keep displaying the raw command exactly as today.
• Show a loading state in the composer area instead of repeating the command.
• Generate a maximum 1–2 sentence plain-English explanation asynchronously.
• Use the existing Settings -> Text generation model configuration.
• Do not introduce a hardcoded model or a separate command-explanation model setting.
• Update the UI when the explanation arrives.
• Associate the result with the approval request ID so a slow response from an older approval cannot appear under a newer one.
• Do not delay or disable any approval action.
• Fall back gracefully if text generation fails.

File-read and file-change approvals can remain unchanged for the first version.

Alternatives considered

Keep displaying the raw command twice.

This keeps the implementation simple but does not help users understand unfamiliar commands, and the lower composer area currently provides little additional value.

Parse commands locally using shell-specific heuristics.

This could explain some common commands without inference latency, but it becomes difficult to maintain across shells, package managers, pipelines, scripts, flags, and project-specific tooling. It also cannot reliably describe intent.

Hardcode a fast model such as Luna specifically for command explanations.

This would work, but T3 Code already has a user-configurable Text generation model used for generated text such as thread titles. A hardcoded model would ignore that setting and create another model-selection policy to maintain.

Add a separate "Approval explanation model" setting.

This seems unnecessary for such a small auxiliary generation task and would add configuration complexity.

The preferred approach is to reuse the existing Text generation model setting and text-generation infrastructure.

Risks or tradeoffs

Generated explanations can be incomplete or incorrect, so they must be presented as informational context rather than as the authoritative description of what will execute. The raw command should always remain visible.

For project-specific scripts, the model should explicitly avoid claiming behavior it cannot infer. For example:

"Runs the project's rename.mjs script. The exact changes depend on the script implementation."

Text generation adds some latency and inference usage, but it should run asynchronously and never block the approval controls.

The result must be associated with the approval request ID so a delayed explanation for one command cannot appear under a later approval.

Users may select a slower or more expensive Text generation model. That is consistent with the existing setting's purpose, and command explanations should respect that existing preference rather than silently selecting another model.

If text generation is unavailable or fails, approval should continue working normally with a simple fallback message.

Examples or references

Relevant current UI:

• apps/web/src/components/chat/ComposerPendingApprovalPanel.tsx
  Displays the pending approval and raw command.

• apps/web/src/components/chat/ChatComposer.tsx
  Currently uses activePendingApproval.detail as the composer placeholder while an approval is active.

• apps/web/src/components/ComposerPromptEditor.tsx
  Renders that placeholder in the lower composer area.

Existing text-generation infrastructure that could be reused:

• apps/server/src/textGeneration/TextGeneration.ts
• apps/server/src/textGeneration/TextGenerationPrompts.ts
• apps/server/src/orchestration/Layers/ProviderCommandReactor.ts

T3 Code already exposes a Settings -> Text generation model option described as the default model for generated text such as thread titles and source-control content. Command explanations should use this same configured model rather than introducing a hardcoded model.

Related but distinct issues:

• [Bug]: File-change approval prompt shows no filename or change details #5255 — file-change approval prompt can omit filename/change details.
• feat: way to view output from tool calls / commands #216 — request to view output from tool calls / commands.

Intended UX:

Before generation completes:

“Explaining this command…”

After generation completes:

"Runs the project's renaming script using Node.js. The exact changes depend on the script implementation."

Contribution

• I would be open to helping implement this.