@esso0428/pi-subagents 0.15.5 → 0.15.7

package/src/index.ts

@@ -24,7 +24,8 @@ import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabl
 import { GroupJoinManager } from "./group-join.js";
 import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
-import { agentHistoryLocator, createAgentHistoryPath, ensureSubagentsGitignore, hasAgentHistory, readAgentHistory } from "./agent-history.js";
+import { agentHistoryLocator, createAgentHistoryPath, readAgentHistory } from "./agent-history.js";
+import { buildAgentStatusMenuEntries, canOpenActiveAgent, canOpenAgentHistory, formatAgentHistoryOption, splitAgentRecords } from "./agent-history-list.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
@@ -49,7 +50,6 @@ import {
   type UICtx,
 } from "./ui/agent-widget.js";
 import { FleetList, type FleetUICtx } from "./ui/fleet-list.js";
-import { createMarkdownResult } from "./ui/markdown-result.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { addUsage, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage } from "./usage.js";
 
@@ -242,9 +242,6 @@ function buildDetails(
   };
 }
 
-/** Maximum expanded notification body retained in message details. */
-const MAX_NOTIFICATION_RESULT_TEXT_LENGTH = 20_000;
-
 /** Build notification details for the custom message renderer. */
 function buildNotificationDetails(record: AgentRecord, resultMaxLen: number, activity?: AgentActivity): NotificationDetails {
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
@@ -260,11 +257,6 @@ function buildNotificationDetails(record: AgentRecord, resultMaxLen: number, act
     durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
     outputFile: record.outputFile,
     error: record.error,
-    resultText: record.result
-      ? record.result.length > MAX_NOTIFICATION_RESULT_TEXT_LENGTH
-        ? record.result.slice(0, MAX_NOTIFICATION_RESULT_TEXT_LENGTH) + "…"
-        : record.result
-      : undefined,
     resultPreview: record.result
       ? record.result.length > resultMaxLen
         ? record.result.slice(0, resultMaxLen) + "…"
@@ -281,7 +273,7 @@ export default function (pi: ExtensionAPI) {
       const d = message.details;
       if (!d) return undefined;
 
-      function renderOne(d: NotificationDetails): string | Container {
+      function renderOne(d: NotificationDetails): string {
         const isError = d.status === "error" || d.status === "stopped" || d.status === "aborted";
         const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
         const statusText = isError ? d.status
@@ -301,34 +293,25 @@ export default function (pi: ExtensionAPI) {
           line += "\n  " + parts.map(p => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
         }
 
-        if (!expanded) {
-          // Collapsed previews intentionally remain compact plain text.
+        // Line 3: result preview (collapsed) or full (expanded)
+        if (expanded) {
+          const lines = d.resultPreview.split("\n").slice(0, 30);
+          for (const l of lines) line += "\n" + theme.fg("dim", `  ${l}`);
+        } else {
           const preview = d.resultPreview.split("\n")[0]?.slice(0, 80) ?? "";
           line += "\n  " + theme.fg("dim", `⎿  ${preview}`);
-          if (d.outputFile) {
-            line += "\n  " + theme.fg("muted", `transcript: ${d.outputFile}`);
-          }
-          return line;
         }
 
-        const container = new Container();
-        container.addChild(new Text(line, 0, 0));
-        container.addChild(createMarkdownResult(d.resultText ?? d.resultPreview, theme, 30));
+        // Line 4: output file link (if present)
         if (d.outputFile) {
-          container.addChild(new Text(theme.fg("muted", `  transcript: ${d.outputFile}`), 0, 0));
+          line += "\n  " + theme.fg("muted", `transcript: ${d.outputFile}`);
         }
-        return container;
+
+        return line;
       }
 
       const all = [d, ...(d.others ?? [])];
-      if (!expanded) return new Text(all.map(renderOne).join("\n"), 0, 0);
-
-      const container = new Container();
-      all.forEach((item, index) => {
-        if (index > 0) container.addChild(new Spacer(1));
-        container.addChild(renderOne(item) as Container);
-      });
-      return container;
+      return new Text(all.map(renderOne).join("\n"), 0, 0);
     }
   );
 
@@ -463,13 +446,14 @@ export default function (pi: ExtensionAPI) {
       pi.events.emit("subagents:completed", eventData);
     }
 
-    // Persist final record for cross-extension history reconstruction. Keep
-    // the transcript body in a project-local file rather than inflating the
-    // parent session JSONL; only its project-relative locator is persisted.
+    // Persist final record for cross-extension history reconstruction
     pi.appendEntry("subagents:record", {
       id: record.id, type: record.type, description: record.description,
       status: record.status, result: record.result, error: record.error,
       startedAt: record.startedAt, completedAt: record.completedAt,
+      toolUses: record.toolUses,
+      lifetimeUsage: record.lifetimeUsage,
+      invocation: record.invocation,
       transcriptPath: record.transcriptPath,
     });
 
@@ -574,22 +558,11 @@ export default function (pi: ExtensionAPI) {
   // bound session_start, so a filtered-out activation never advertises (#142).
   pi.on("session_start", async (_event, ctx) => {
     currentCtx = ctx;
-    try {
-      ensureSubagentsGitignore(ctx.cwd);
-    } catch (err) {
-      console.warn("[pi-subagents] Failed to protect project-local history:", err);
-    }
     manager.clearCompleted(true);
-    const historicalRecords = ctx.sessionManager
-      .getBranch()
-      .filter((entry: any) => entry?.type === "custom" && entry.customType === "subagents:record")
-      .map((entry: any) => entry.data);
-    manager.restoreCompleted(historicalRecords);
-    // Bind the UI here as well as on tool execution so rehydrated terminal
-    // records are immediately visible and openable from FleetView after reload.
-    widget.setUICtx(ctx.ui as UICtx);
-    fleet.setUICtx(ctx.ui as unknown as FleetUICtx);
-    fleet.update();
+    const branch = ctx.sessionManager?.getBranch?.() ?? [];
+    manager.restoreCompleted(branch
+      .filter((entry: any) => entry?.type === "custom" && entry?.customType === "subagents:record")
+      .map((entry: any) => entry.data));
     // Guard mirrors the `!scheduler.isActive()` pattern below: session_start
     // fires once per activation, but a double-bind must not leak listeners.
     if (!rpcHandle) {
@@ -640,11 +613,11 @@ export default function (pi: ExtensionAPI) {
   // everything else; "off" = hide the widget entirely. Read live at render time.
   let widgetMode: WidgetMode = "background";
   function getWidgetMode(): WidgetMode { return widgetMode; }
-  const widget = new AgentWidget(manager, agentActivity, getWidgetMode, () => currentCtx?.cwd);
+  const widget = new AgentWidget(manager, agentActivity, getWidgetMode);
   function setWidgetMode(m: WidgetMode): void { widgetMode = m; widget.update(); }
 
   // Claude Code-style FleetView: navigable list of main + subagents below the editor.
-  const fleet = new FleetList(manager, agentActivity, () => currentCtx?.cwd);
+  const fleet = new FleetList(manager, agentActivity, () => currentCtx?.cwd, pi, () => currentCtx);
   let fleetViewEnabled = true;
   function isFleetViewEnabled(): boolean { return fleetViewEnabled; }
   function setFleetViewEnabled(b: boolean): void { fleetViewEnabled = b; fleet.setEnabled(b); }
@@ -1061,15 +1034,15 @@ Terse command-style prompts produce shallow, generic work.
 
         if (expanded) {
           const resultText = result.content[0]?.type === "text" ? result.content[0].text : "";
-          const container = new Container();
-          container.addChild(new Text(line, 0, 0));
           if (resultText) {
-            container.addChild(createMarkdownResult(resultText, theme, 50));
+            const lines = resultText.split("\n").slice(0, 50);
+            for (const l of lines) {
+              line += "\n" + theme.fg("dim", `  ${l}`);
+            }
             if (resultText.split("\n").length > 50) {
-              container.addChild(new Text(theme.fg("muted", "  ... (use get_subagent_result with verbose for full output)"), 0, 0));
+              line += "\n" + theme.fg("muted", "  ... (use get_subagent_result with verbose for full output)");
             }
           }
-          return container;
         } else {
           const doneText = isSteered ? "Wrapped up (turn limit)" : "Done";
           line += "\n" + theme.fg("dim", `  ⎿  ${doneText}`);
@@ -1176,17 +1149,17 @@ Terse command-style prompts produce shallow, generic work.
         rec.outputFile = createOutputFilePath(ctx.cwd, agentId, ctx.sessionManager.getSessionId());
         writeInitialEntry(rec.outputFile, agentId, params.prompt, ctx.cwd);
 
-        // Keep the existing /tmp output for compatibility, while also writing a
-        // durable project-local copy for reload-safe, read-only history viewing.
         try {
-          rec.historyFile = createAgentHistoryPath(ctx.cwd, agentId, subagentType);
+          rec.historyFile = createAgentHistoryPath(ctx.cwd, agentId);
           rec.transcriptPath = agentHistoryLocator(ctx.cwd, rec.historyFile);
           writeInitialEntry(rec.historyFile, agentId, params.prompt, ctx.cwd);
         } catch (err) {
-          // History is best effort; never disable the existing output transcript.
           rec.historyFile = undefined;
           rec.transcriptPath = undefined;
-          console.warn("[pi-subagents] Failed to create durable transcript:", err);
+          ctx.ui.notify(
+            `Could not create durable transcript for agent ${agentId}: ${err instanceof Error ? err.message : String(err)}`,
+            "warning",
+          );
         }
       };
 
@@ -1198,7 +1171,9 @@ Terse command-style prompts produce shallow, generic work.
       const effectiveMaxTurns = normalizeMaxTurns(resolvedConfig.maxTurns ?? getDefaultMaxTurns());
       const agentInvocation: AgentInvocation = {
         modelName,
+        effectiveModelName: model?.name ?? model?.id ?? ctx.model?.name ?? ctx.model?.id,
         thinking,
+        effectiveThinking: thinking,
         // Explicit value only — the default fallback would just add noise.
         // Normalize so `0` (unlimited) doesn't surface as a misleading "max turns: 0".
         maxTurns: normalizeMaxTurns(resolvedConfig.maxTurns),
@@ -1667,17 +1642,10 @@ Terse command-style prompts produce shallow, generic work.
     // Build select options
     const options: string[] = [];
 
-    // Only advertise agents that can actually be opened. Reload-restored
-    // metadata without a live session or durable transcript is intentionally
-    // invisible here, matching FleetView and showRunningAgents below.
-    const agents = manager.listAgents().filter((record) =>
-      record.session !== undefined || hasAgentHistory(ctx.cwd, record.transcriptPath),
-    );
-    if (agents.length > 0) {
-      const running = agents.filter(a => a.status === "running" || a.status === "queued").length;
-      const done = agents.filter(a => a.status === "completed" || a.status === "steered").length;
-      options.push(`Running agents (${agents.length}) — ${running} running, ${done} done`);
-    }
+    // Keep active agents and terminal history in separate menu entries.
+    const records = manager.listAgents();
+    const { active, history } = splitAgentRecords(records, ctx.cwd);
+    options.push(...buildAgentStatusMenuEntries(records, ctx.cwd));
 
     // Agent types list
     if (allNames.length > 0) {
@@ -1694,7 +1662,7 @@ Terse command-style prompts produce shallow, generic work.
     options.push("Create new agent");
     options.push("Settings");
 
-    const noAgentsMsg = allNames.length === 0 && agents.length === 0
+    const noAgentsMsg = allNames.length === 0 && active.length === 0 && history.length === 0
       ? "No agents found. Create specialized subagents that can be delegated to.\n\n" +
         "Each subagent has its own context window, custom system prompt, and specific tools.\n\n" +
         "Try creating: Code Reviewer, Security Auditor, Test Writer, or Documentation Writer.\n\n"
@@ -1710,6 +1678,9 @@ Terse command-style prompts produce shallow, generic work.
     if (choice.startsWith("Running agents (")) {
       await showRunningAgents(ctx);
       await showAgentsMenu(ctx);
+    } else if (choice.startsWith("Agent history (")) {
+      await showAgentHistory(ctx);
+      await showAgentsMenu(ctx);
     } else if (choice.startsWith("Agent types (")) {
       await showAllAgentsList(ctx);
       await showAgentsMenu(ctx);
@@ -1792,54 +1763,101 @@ Terse command-style prompts produce shallow, generic work.
     }
   }
 
+  function makeUniqueAgentOptionLabels(pairs: Array<{ record: AgentRecord; label: string }>): string[] {
+    const counts = new Map<string, number>();
+    for (const pair of pairs) counts.set(pair.label, (counts.get(pair.label) ?? 0) + 1);
+    const used = new Set<string>();
+    return pairs.map((pair) => {
+      const { record, label } = pair;
+      if ((counts.get(label) ?? 0) === 1) {
+        used.add(label);
+        return label;
+      }
+      const suffix = ` · #${record.id.slice(-8)}`;
+      let candidate = `${label}${suffix}`;
+      let n = 2;
+      while (used.has(candidate)) candidate = `${label}${suffix}-${n++}`;
+      used.add(candidate);
+      pair.label = candidate;
+      return candidate;
+    });
+  }
+
   async function showRunningAgents(ctx: ExtensionCommandContext) {
-    const agents = manager.listAgents().filter((record) =>
-      record.session !== undefined || hasAgentHistory(ctx.cwd, record.transcriptPath),
-    );
+    const { active: agents } = splitAgentRecords(manager.listAgents(), ctx.cwd);
     if (agents.length === 0) {
       ctx.ui.notify("No agents.", "info");
       return;
     }
 
-    const options = agents.map(a => {
-      const dn = getDisplayName(a.type);
-      const dur = formatDuration(a.startedAt, a.completedAt);
-      return `${dn} (${a.description}) · ${a.toolUses} tools · ${a.status} · ${dur}`;
+    const pairs = agents.map((record) => {
+      const dn = getDisplayName(record.type);
+      const dur = formatDuration(record.startedAt, record.completedAt);
+      return { record, label: `${dn} (${record.description}) · ${record.toolUses} tools · ${record.status} · ${dur}` };
     });
+    const options = makeUniqueAgentOptionLabels(pairs);
 
     const choice = await ctx.ui.select("Running agents", options);
     if (!choice) return;
+    const record = pairs.find((pair) => pair.label === choice)?.record;
+    if (!record) return;
 
-    // Find the selected agent by matching the option index
-    const idx = options.indexOf(choice);
-    if (idx < 0) return;
-    const record = agents[idx];
-
-    await viewAgentConversation(ctx, record);
+    await viewAgentConversation(ctx, record, "live");
     // Back-navigation: re-show the list
     await showRunningAgents(ctx);
   }
 
-  async function viewAgentConversation(ctx: ExtensionCommandContext, record: AgentRecord) {
-    if (!record.session) {
-      ctx.ui.notify(`Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`, "info");
+  async function showAgentHistory(ctx: ExtensionCommandContext) {
+    const { history } = splitAgentRecords(manager.listAgents(), ctx.cwd);
+    if (history.length === 0) {
+      ctx.ui.notify("No agent history.", "info");
+      return;
+    }
+
+    const pairs = history.map((record) => ({ record, label: formatAgentHistoryOption(record, Date.now()) }));
+    const options = makeUniqueAgentOptionLabels(pairs);
+    const choice = await ctx.ui.select("Agent history", options);
+    if (!choice) return;
+    const record = pairs.find((pair) => pair.label === choice)?.record;
+    if (!record) return;
+
+    await viewAgentConversation(ctx, record, "history");
+  }
+
+  async function viewAgentConversation(
+    ctx: ExtensionCommandContext,
+    record: AgentRecord,
+    mode: "live" | "history",
+  ) {
+    if (mode === "live" && !canOpenActiveAgent(record)) {
+      ctx.ui.notify(`Agent is ${record.status === "queued" ? "queued" : "expired"} — no history available.`, "info");
+      return;
+    }
+    if (mode === "history" && !canOpenAgentHistory(record, ctx.cwd)) {
+      ctx.ui.notify("No agent history.", "info");
       return;
     }
 
     const { ConversationViewer, VIEWPORT_HEIGHT_PCT, createStaticConversationSource } = await import("./ui/conversation-viewer.js");
-    const session = record.session ?? (record.transcriptPath
-      ? (() => {
-          const messages = readAgentHistory(ctx.cwd, record.transcriptPath!);
-          return messages ? createStaticConversationSource(messages) : undefined;
-        })()
-      : undefined);
+    const session = mode === "live"
+      ? record.session
+      : (() => {
+          const messages = record.transcriptPath
+            ? readAgentHistory(ctx.cwd, record.transcriptPath)
+            : undefined;
+          return messages
+            ? createStaticConversationSource(messages)
+            : record.session
+              ? createStaticConversationSource(record.session.messages)
+              : undefined;
+        })();
     if (!session) {
-      ctx.ui.notify(`Agent is ${record.status === "queued" ? "queued" : "expired"} — no history available.`, "info");
+      ctx.ui.notify("No agent history.", "info");
       return;
     }
-    const activity = agentActivity.get(record.id);
-    const isLive = record.session !== undefined;
 
+    const activity = agentActivity.get(record.id);
+    const isLive = mode === "live";
     await ctx.ui.custom<undefined>(
       (tui, theme, keybindings, done) => {
         return new ConversationViewer(tui, session, record, activity, theme, done,
@@ -1849,7 +1867,8 @@ Terse command-style prompts produce shallow, generic work.
             }
           } : undefined,
           keybindings,
-          isLive ? (message: string) => manager.steer(record.id, message) : undefined);
+          isLive ? (message: string) => manager.steer(record.id, message) : undefined,
+          mode === "history" ? { pi, ctx, readOnly: true } : { pi, ctx });
       },
       {
         overlay: true,

package/src/output-file.ts

@@ -65,8 +65,8 @@ export function streamToOutputFile(
   cwd: string,
   historyPath?: string,
 ): () => void {
-  const outputPaths = historyPath && historyPath !== path ? [path, historyPath] : [path];
   let writtenCount = 1; // initial user prompt already written
+  const outputPaths = historyPath && historyPath !== path ? [path, historyPath] : [path];
 
   const flush = () => {
     const messages = session.messages;

package/src/types.ts

@@ -137,6 +137,10 @@ export interface AgentRecord {
 export interface AgentInvocation {
   /** Short display name, e.g. "haiku" — only set when different from parent. */
   modelName?: string;
+  /** Effective model captured from the child session, including inherited models. */
+  effectiveModelName?: string;
+  /** Requested/ effective thinking level. */
+  effectiveThinking?: AgentSession["thinkingLevel"];
   thinking?: ThinkingLevel;
   maxTurns?: number;
   isolated?: boolean;
@@ -158,7 +162,6 @@ export interface NotificationDetails {
   outputFile?: string;
   error?: string;
   resultPreview: string;
-  resultText?: string;
   /** Additional agents in a group notification. */
   others?: NotificationDetails[];
 }

package/src/ui/agent-widget.ts

@@ -6,7 +6,6 @@
  */
 
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import { hasAgentHistory } from "../agent-history.js";
 import type { AgentManager } from "../agent-manager.js";
 import { getConfig } from "../agent-types.js";
 import type { AgentInvocation, SubagentType, WidgetMode } from "../types.js";
@@ -167,7 +166,8 @@ export function buildInvocationTags(
 ): { modelName?: string; tags: string[] } {
   const tags: string[] = [];
   if (!invocation) return { tags };
-  if (invocation.thinking) tags.push(`thinking: ${invocation.thinking}`);
+  const thinking = invocation.effectiveThinking ?? invocation.thinking;
+  if (thinking) tags.push(`thinking: ${thinking}`);
   if (invocation.isolated) tags.push("isolated");
   if (invocation.isolation === "worktree") tags.push("worktree");
   if (invocation.inheritContext) tags.push("inherit context");
@@ -238,8 +238,6 @@ export class AgentWidget {
      * extension supplies one defaulting to `"background"`.
      */
     private mode: () => WidgetMode = () => "all",
-    /** Current project cwd used to validate reload-restored transcripts. */
-    private getCwd: () => string | undefined = () => undefined,
   ) {}
 
   /**
@@ -254,11 +252,7 @@ export class AgentWidget {
    *   - `all`: every agent.
    */
   private widgetAgents() {
-    const all = this.manager.listAgents().filter((record) => {
-      if (record.status === "running" || record.status === "queued") return true;
-      const cwd = this.getCwd();
-      return cwd !== undefined && hasAgentHistory(cwd, record.transcriptPath);
-    });
+    const all = this.manager.listAgents();
     switch (this.mode()) {
       case "off": return [];
       case "background": return all.filter(a => a.isBackground !== false);

package/src/ui/ccstyle/ATTRIBUTION.md

@@ -0,0 +1,37 @@
+# Attribution
+
+The viewer-local ccstyle tool-card and diff renderer are adapted from
+`@herbertgao/pi-cc-extensions` version `0.9.0`, specifically its
+`extensions/renderer/tool/result.ts` and
+`extensions/renderer/tool/diff/` modules.
+
+The adaptation is local to this package and changes the configuration boundary,
+write payload handling, width guards, and syntax highlighting fallback. It does
+not install `@shikijs/cli`, patch Pi prototypes, or register global terminal
+handlers. The local copy uses Pi's public `highlightCode` API and plain text
+when highlighting is unavailable.
+
+The source package is distributed under the MIT License. The relevant license
+text is reproduced below:
+
+> MIT License
+>
+> Copyright (c) 2026 Herbert Gao and pi-cc-extensions contributors
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.

package/src/ui/ccstyle/diff/ansi-utils.ts

@@ -0,0 +1,168 @@
+const ANSI_SGR_PATTERN = /\x1b\[([0-9;]*)m/g;
+const ANSI_SGR_WITH_COLON_PATTERN = /\x1b\[([0-9;:]*)m/g;
+const STYLE_RESET_PARAMS = [39, 22, 23, 24, 25, 27, 28, 29, 59] as const;
+
+export { ANSI_SGR_PATTERN, STYLE_RESET_PARAMS };
+
+export function expandSgrReset(param: number): readonly number[] | undefined {
+	return param === 0 ? STYLE_RESET_PARAMS : undefined;
+}
+
+export function toSgrParams(rawParams: string): number[] {
+	if (!rawParams.trim()) {
+		return [0];
+	}
+
+	const parsed = rawParams
+		.split(";")
+		.map((token) => Number.parseInt(token, 10))
+		.filter((value) => Number.isFinite(value));
+
+	return parsed.length > 0 ? parsed : [];
+}
+
+export function isFiniteSgrParam(value: number | undefined): value is number {
+	return typeof value === "number" && Number.isFinite(value);
+}
+
+export function readSgrColorSequence(params: number[], index: number): number[] | undefined {
+	const param = params[index];
+	if (param !== 38 && param !== 48) {
+		return undefined;
+	}
+
+	const colorMode = params[index + 1];
+	if (colorMode === 5) {
+		const colorValue = params[index + 2];
+		return isFiniteSgrParam(colorValue) ? [param, colorMode, colorValue] : undefined;
+	}
+
+	if (colorMode === 2) {
+		const red = params[index + 2];
+		const green = params[index + 3];
+		const blue = params[index + 4];
+		return isFiniteSgrParam(red) && isFiniteSgrParam(green) && isFiniteSgrParam(blue)
+			? [param, colorMode, red, green, blue]
+			: undefined;
+	}
+
+	return undefined;
+}
+
+export function stripBackgroundSgrParams(params: readonly number[]): number[] {
+	const sanitized: number[] = [];
+
+	for (let index = 0; index < params.length; index++) {
+		const param = params[index] ?? 0;
+
+		if (param === 0) {
+			sanitized.push(...expandSgrReset(param)!);
+			continue;
+		}
+
+		if (param === 49 || (param >= 40 && param <= 47) || (param >= 100 && param <= 107)) {
+			continue;
+		}
+
+		if (param === 38 || param === 48) {
+			const sequence = readSgrColorSequence(params as number[], index);
+			if (sequence) {
+				if (param === 38) {
+					sanitized.push(...sequence);
+				}
+				index += sequence.length - 1;
+				continue;
+			}
+			const advance = params[index + 1] === 5 ? 2 : params[index + 1] === 2 ? 4 : 0;
+			if (advance > 0) {
+				index += advance;
+				if (param === 38) {
+					sanitized.push(param);
+				}
+				continue;
+			}
+		}
+
+		sanitized.push(param);
+	}
+
+	return sanitized;
+}
+
+export function filterSgrSequences(text: string, filter: (params: number[]) => number[]): string {
+	if (!text || !text.includes("\x1b[")) {
+		return text;
+	}
+
+	return text.replace(ANSI_SGR_PATTERN, (_sequence, rawParams: string) => {
+		const parsed = toSgrParams(rawParams);
+		if (parsed.length === 0) {
+			return "";
+		}
+
+		const sanitized = filter(parsed);
+		if (sanitized.length === 0) {
+			return "";
+		}
+
+		return `\x1b[${sanitized.join(";")}m`;
+	});
+}
+
+function isValidColonForeground(segment: string): boolean {
+	const params = segment.split(":");
+	const isByte = (value: string | undefined) =>
+		value !== undefined && /^\d+$/.test(value) && Number(value) <= 255;
+	if (params[0] !== "38") return false;
+	if (params[1] === "5") return params.length === 3 && isByte(params[2]);
+	return (
+		params[1] === "2" &&
+		params.length === 6 &&
+		(params[2] === "" || /^\d+$/.test(params[2] ?? "")) &&
+		params.slice(3).every(isByte)
+	);
+}
+
+function sanitizeColonSgr(rawParams: string): string {
+	const segments = rawParams.split(";");
+	const sanitized: string[] = [];
+	for (let index = 0; index < segments.length; index++) {
+		const segment = segments[index] ?? "";
+		if (segment.includes(":")) {
+			const code = Number.parseInt(segment, 10);
+			if (code !== 48 && (code !== 38 || isValidColonForeground(segment))) {
+				sanitized.push(segment);
+			}
+			continue;
+		}
+		const param = Number.parseInt(segment, 10);
+		if (!Number.isFinite(param)) continue;
+		if (param === 0) {
+			sanitized.push(...STYLE_RESET_PARAMS.map(String));
+			continue;
+		}
+		if (param === 49 || (param >= 40 && param <= 47) || (param >= 100 && param <= 107)) {
+			continue;
+		}
+		if (param === 38 || param === 48) {
+			const mode = Number.parseInt(segments[index + 1] ?? "", 10);
+			const advance = mode === 5 ? 2 : mode === 2 ? 4 : 0;
+			if (advance > 0) {
+				if (param === 38) sanitized.push(...segments.slice(index, index + advance + 1));
+				index += advance;
+				continue;
+			}
+		}
+		sanitized.push(segment);
+	}
+	return sanitized.length > 0 ? `\x1b[${sanitized.join(";")}m` : "";
+}
+
+export function sanitizeAnsiForThemedOutput(text: string): string {
+	if (!text || !text.includes("\x1b[")) return text;
+	return text.replace(ANSI_SGR_WITH_COLON_PATTERN, (sequence, rawParams: string) =>
+		rawParams.includes(":")
+			? sanitizeColonSgr(rawParams)
+			: filterSgrSequences(sequence, stripBackgroundSgrParams),
+	);
+}