praxis-agent 0.15.0 → 0.16.0

package/README.md

@@ -95,7 +95,8 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   tabs, `/sandbox` mode/dependency/override/config controls, local cached
   `/release-notes`, Claude-compatible `/statusline` command execution and setup
   agent, source-aligned `/init` project-instruction onboarding with its enhanced
-  skills/hooks flow, `/mcp`, `/memory` shared instruction and auto-memory
+  skills/hooks flow, provider-free per-session `/color` prompt-bar styling,
+  `/mcp`, `/memory` shared instruction and auto-memory
   access, and live extension-reload controls,
   cursor/history composer, per-session model/effort/permission controls,
   context/status/skill/task dashboards, prompt stash and continuation shortcuts,

package/dist/application/session-service.d.ts

@@ -1,3 +1,4 @@
+import { type AgentColorName, type AgentColorSelection } from '../compatibility/claude/agent-color.js';
 import type { ClaudeConditionalRuleResolver } from '../compatibility/claude/context.js';
 import { type ClaudeFileResource, type ClaudeFileResourceConfig } from '../compatibility/claude/file-resources.js';
 import { type ClaudeDisplayTranscriptItem } from '../compatibility/claude/projection.js';
@@ -182,6 +183,7 @@ export declare class ClaudeSessionService {
     sessionNameSuggestion(sessionId: string, signal?: AbortSignal): Promise<string | null>;
     sessions(): Promise<SessionSummary[]>;
     inspect(sessionId: string): Promise<SessionInspection>;
+    readEffectiveAgentColor(sessionId: string): Promise<AgentColorName | undefined>;
     export(sessionId: string): Promise<Buffer>;
     transcript(sessionId: string, resumeSessionAt?: string): Promise<ClaudeDisplayTranscriptItem[]>;
     rename(sessionId: string, name: string): Promise<void>;
@@ -190,6 +192,9 @@ export declare class ClaudeSessionService {
     approveRecentlyDenied(sessionId: string, display: string): Promise<void>;
     retryRecentlyDenied(sessionId: string, display: string, signal?: AbortSignal): Promise<SessionRunResult>;
     recordBtwUsage(sessionId: string | undefined, permissionMode?: ClaudePermissionMode): Promise<string>;
+    recordColorUsage(sessionId: string | undefined, selection: AgentColorSelection, display: string, permissionMode?: ClaudePermissionMode, options?: {
+        createSession?: boolean;
+    }): Promise<string>;
     recordBackgroundUsage(sessionId: string | undefined, permissionMode?: ClaudePermissionMode): Promise<string>;
     recordBackgroundLaunch(sessionId: string): Promise<SessionForkCheckpoint>;
     compact(sessionId: string, signal?: AbortSignal, selection?: ManualCompactSelection): Promise<ManualCompactResult>;
@@ -214,6 +219,7 @@ export declare class ClaudeSessionService {
     private restoreWorktree;
     private paths;
     private appendCdCommand;
+    private appendAgentColorUsage;
     private appendSystemLocalCommand;
     private ensureLocalSession;
     private appendInputHistory;

package/dist/application/session-service.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { appendFile, copyFile, link, lstat, mkdir, readdir, realpath, stat, unlink, } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, extname, isAbsolute, join, relative } from 'node:path';
+import { AGENT_COLOR_DEFAULT, agentColorMessage, getClaudeEffectiveAgentColor, } from '../compatibility/claude/agent-color.js';
 import { createClaudeCompactEntries, formatClaudeCompactSummary, getCumulativeDroppedTokens, } from '../compatibility/claude/compaction.js';
 import { isClaudeSessionId, resolveClaudePaths, resolveClaudeScheduledTaskFile, } from '../compatibility/claude/paths.js';
 import { downloadClaudeFileResources, } from '../compatibility/claude/file-resources.js';
@@ -696,6 +697,11 @@ export class ClaudeSessionService {
                 : {}),
         };
     }
+    async readEffectiveAgentColor(sessionId) {
+        this.assertSessionPersistence();
+        const recovery = await this.store(sessionId).loadReadOnly();
+        return getClaudeEffectiveAgentColor(recovery.entries, sessionId);
+    }
     async export(sessionId) {
         this.assertSessionPersistence();
         try {
@@ -934,6 +940,21 @@ export class ClaudeSessionService {
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
     }
+    async recordColorUsage(sessionId, selection, display, permissionMode = 'default', options = {}) {
+        const output = agentColorMessage(selection);
+        const agentColor = selection.kind === 'color'
+            ? selection.color
+            : selection.kind === 'reset'
+                ? AGENT_COLOR_DEFAULT
+                : undefined;
+        const createLocalSession = sessionId === undefined || options.createSession === true;
+        const activeSessionId = await this.ensureLocalSession(sessionId, permissionMode, createLocalSession ? agentColor : undefined, options.createSession === true);
+        if (this.options.sessionPersistence !== false) {
+            await this.appendInputHistory(display, activeSessionId);
+        }
+        await this.appendAgentColorUsage(activeSessionId, display, output, createLocalSession ? undefined : agentColor);
+        return activeSessionId;
+    }
     async recordBackgroundUsage(sessionId, permissionMode = 'default') {
         this.assertWritable();
         const activeSessionId = await this.ensureLocalSession(sessionId, permissionMode);
@@ -2566,6 +2587,35 @@ export class ClaudeSessionService {
             throw new Error(`Claude local command conflict: ${result.reason}`);
         }
     }
+    async appendAgentColorUsage(sessionId, display, output, agentColor) {
+        const args = display.replace(/^\/color\s*/u, '').trim();
+        while (true) {
+            const result = await this.turnStore(sessionId).withLease(async (lease) => {
+                const snapshot = await lease.load();
+                if (snapshot.entries.length === 0) {
+                    throw new Error(`Claude session not found: ${sessionId}`);
+                }
+                const appended = await lease.appendMany(snapshot.tail, [
+                    ...(agentColor === undefined
+                        ? []
+                        : [
+                            {
+                                type: 'agent-color',
+                                agentColor,
+                                sessionId,
+                            },
+                        ]),
+                    ...this.localCommandEntries(sessionId, this.activeCwd(), this.logicalTailUuid(snapshot.tail), 'color', args, output),
+                ]);
+                if (appended.status === 'conflict') {
+                    throw new Error(`Claude color local command append conflict: ${appended.reason}`);
+                }
+            });
+            if (result.status === 'completed')
+                return;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+    }
     async appendSystemLocalCommand(sessionId, command, args, output) {
         while (true) {
             const result = await this.turnStore(sessionId).withLease(async (lease) => {
@@ -2583,13 +2633,22 @@ export class ClaudeSessionService {
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
     }
-    async ensureLocalSession(sessionId, permissionMode) {
-        if (sessionId)
+    async ensureLocalSession(sessionId, permissionMode, agentColor, createExplicit = false) {
+        if (sessionId !== undefined && !createExplicit)
             return sessionId;
         this.assertWritable();
-        const createdSessionId = randomUUID();
+        const createdSessionId = sessionId ?? randomUUID();
         const store = this.turnStore(createdSessionId);
         const created = await store.create([
+            ...(agentColor === undefined
+                ? []
+                : [
+                    {
+                        type: 'agent-color',
+                        agentColor,
+                        sessionId: createdSessionId,
+                    },
+                ]),
             { type: 'mode', mode: 'normal', sessionId: createdSessionId },
             {
                 type: 'permission-mode',

package/dist/cli/interactive.d.ts

@@ -8,6 +8,8 @@ import { type TuiMemoryFiles } from './tui/memory-files.js';
 import { type TuiDiffSnapshot } from './tui/git-diff.js';
 import { type TuiPermissionBehavior, type TuiPermissionRule } from './tui/permission-settings.js';
 import { type RecentlyDeniedStore } from './tui/recently-denied.js';
+import { type AgentColorSelection } from '../compatibility/claude/agent-color.js';
+import type { AgentColorName } from '../compatibility/claude/agent-color.js';
 import type { ClaudeResourceScope } from '../compatibility/claude/shared-resources.js';
 import type { TuiHookConfiguration } from './tui/hook-settings.js';
 import { type TuiSlashCommand } from './tui/slash-commands.js';
@@ -41,6 +43,8 @@ interface InteractiveSessionCommands {
     retryRecentlyDenied?(sessionId: string, display: string, signal?: AbortSignal): Promise<SessionRunResult>;
     answerSideQuestion?(sessionId: string | undefined, question: string, signal?: AbortSignal, onDelta?: (delta: string) => void, permissionMode?: ClaudePermissionMode): Promise<SideQuestionResult>;
     recordBtwUsage?(sessionId: string | undefined, permissionMode?: ClaudePermissionMode): Promise<string>;
+    recordColorUsage?(sessionId: string | undefined, selection: AgentColorSelection, display: string, permissionMode?: ClaudePermissionMode): Promise<string>;
+    agentColor?(sessionId: string): Promise<AgentColorName | undefined>;
     recordBackgroundUsage?(sessionId: string | undefined, permissionMode?: ClaudePermissionMode): Promise<string>;
     recordBackgroundLaunch?(sessionId: string): Promise<SessionForkCheckpoint>;
     forkSideQuestion?(sessionId: string, question: string, signal?: AbortSignal): Promise<SideQuestionForkResult>;
@@ -111,6 +115,7 @@ interface InteractiveAppProps {
     initialSessions: readonly SessionSummary[];
     initialPrompt?: string;
     initialHistory?: readonly TranscriptItem[];
+    initialSessionColor?: AgentColorName;
     signal?: AbortSignal;
     onCancel?: () => void;
     onTurnChange?: (turn: Promise<void> | null) => void;
@@ -179,7 +184,7 @@ interface InteractiveAppProps {
     releaseNotesLoader?: (configRoot: string) => Promise<string>;
     settingSources?: readonly ClaudeResourceScope[];
 }
-export declare function InteractiveApp({ factory, initialSessions, initialPrompt, initialHistory, signal, onCancel, onTurnChange, onCleanup, onRendererChange, onBackground, axScreenReader, allowNewSession, resume, display, terminalWidth, slashCommands, agents, allowDangerouslySkipPermissions, additionalDirectories, diffLoader, fileLoader, externalEditor, keybindingsConfigRoot, keybindingsFile, keybindingsLoader, keybindingsEditor, memoryFilesLoader, memoryEditor, memoryFolderOpener, suspendProcess, clipboardReader, clipboardWriter, sideQuestionClipboardWriter, exportWriter, permissionRuleStore, sandboxStore: suppliedSandboxStore, recentlyDeniedStore: suppliedRecentlyDeniedStore, terminalSetup: terminalSetupOverride, themeStore, initialThemeSettings, initialThemeLoadError, workspaceDirectoryResolver, workspaceDirectoryCompleter, runtimeSettings: suppliedRuntimeSettings, runtimeSettingsTarget, notificationWriter, elicitationUrlOpener, releaseNotesLoader, settingSources, }: InteractiveAppProps): import("react").JSX.Element;
+export declare function InteractiveApp({ factory, initialSessions, initialPrompt, initialHistory, initialSessionColor, signal, onCancel, onTurnChange, onCleanup, onRendererChange, onBackground, axScreenReader, allowNewSession, resume, display, terminalWidth, slashCommands, agents, allowDangerouslySkipPermissions, additionalDirectories, diffLoader, fileLoader, externalEditor, keybindingsConfigRoot, keybindingsFile, keybindingsLoader, keybindingsEditor, memoryFilesLoader, memoryEditor, memoryFolderOpener, suspendProcess, clipboardReader, clipboardWriter, sideQuestionClipboardWriter, exportWriter, permissionRuleStore, sandboxStore: suppliedSandboxStore, recentlyDeniedStore: suppliedRecentlyDeniedStore, terminalSetup: terminalSetupOverride, themeStore, initialThemeSettings, initialThemeLoadError, workspaceDirectoryResolver, workspaceDirectoryCompleter, runtimeSettings: suppliedRuntimeSettings, runtimeSettingsTarget, notificationWriter, elicitationUrlOpener, releaseNotesLoader, settingSources, }: InteractiveAppProps): import("react").JSX.Element;
 export declare function runInteractive(options: {
     factory: InteractiveServiceFactory;
     initialPrompt?: string;

package/dist/cli/interactive.js

@@ -17,6 +17,7 @@ import { createClaudeStatusLineInput, StatusLine } from './tui/status-line.js';
 import { loadGitDiff, visiblePatchLines, } from './tui/git-diff.js';
 import { addTuiPermissionRule, loadTuiPermissionRules, removeTuiPermissionRule, } from './tui/permission-settings.js';
 import { createRecentlyDeniedStore, } from './tui/recently-denied.js';
+import { agentColorMessage, parseAgentColorInput, } from '../compatibility/claude/agent-color.js';
 import { filterTuiSlashCommands, mergeTuiSlashCommands, slashCommandQuery, } from './tui/slash-commands.js';
 import { createComposerEditor, deleteComposerBackward, deleteComposerForward, deleteComposerToEnd, deleteComposerToStart, deleteComposerWordBackward, insertComposerText, moveComposerCursor, moveComposerCursorByWord, } from './tui/composer-editor.js';
 import { applyMentionReference, fileReferenceAtCursor, filterTuiMentionEntries, loadTuiFileEntries, } from './tui/file-picker.js';
@@ -247,7 +248,7 @@ const HIDDEN_TUI_SLASH_COMMANDS = new Set([
     'update',
     'usage',
 ]);
-export function InteractiveApp({ factory, initialSessions, initialPrompt, initialHistory = [], signal, onCancel, onTurnChange, onCleanup, onRendererChange, onBackground, axScreenReader = false, allowNewSession = true, resume, display = { version: 'dev', cwd: process.cwd() }, terminalWidth, slashCommands = EMPTY_SLASH_COMMANDS, agents = EMPTY_AGENTS, allowDangerouslySkipPermissions = false, additionalDirectories = [], diffLoader, fileLoader, externalEditor = editTuiPrompt, keybindingsConfigRoot, keybindingsFile = ensureTuiKeybindingsFile, keybindingsLoader = loadTuiKeybindings, keybindingsEditor = openTuiEditorFile, memoryFilesLoader = (configRoot, cwd) => loadTuiMemoryFiles({ configRoot, cwd }), memoryEditor = openTuiEditorFile, memoryFolderOpener = openTuiMemoryFolder, suspendProcess = suspendTuiProcess, clipboardReader = readTuiClipboard, clipboardWriter = writeTuiClipboard, sideQuestionClipboardWriter = writeTuiOsc52Clipboard, exportWriter = writeConversationExport, permissionRuleStore, sandboxStore: suppliedSandboxStore, recentlyDeniedStore: suppliedRecentlyDeniedStore, terminalSetup: terminalSetupOverride, themeStore, initialThemeSettings, initialThemeLoadError, workspaceDirectoryResolver = resolveTuiWorkspaceDirectory, workspaceDirectoryCompleter = completeTuiWorkspaceDirectory, runtimeSettings: suppliedRuntimeSettings, runtimeSettingsTarget, notificationWriter, elicitationUrlOpener = openTuiUrl, releaseNotesLoader = (configRoot) => loadClaudeReleaseNotes({ configRoot }), settingSources, }) {
+export function InteractiveApp({ factory, initialSessions, initialPrompt, initialHistory = [], initialSessionColor, signal, onCancel, onTurnChange, onCleanup, onRendererChange, onBackground, axScreenReader = false, allowNewSession = true, resume, display = { version: 'dev', cwd: process.cwd() }, terminalWidth, slashCommands = EMPTY_SLASH_COMMANDS, agents = EMPTY_AGENTS, allowDangerouslySkipPermissions = false, additionalDirectories = [], diffLoader, fileLoader, externalEditor = editTuiPrompt, keybindingsConfigRoot, keybindingsFile = ensureTuiKeybindingsFile, keybindingsLoader = loadTuiKeybindings, keybindingsEditor = openTuiEditorFile, memoryFilesLoader = (configRoot, cwd) => loadTuiMemoryFiles({ configRoot, cwd }), memoryEditor = openTuiEditorFile, memoryFolderOpener = openTuiMemoryFolder, suspendProcess = suspendTuiProcess, clipboardReader = readTuiClipboard, clipboardWriter = writeTuiClipboard, sideQuestionClipboardWriter = writeTuiOsc52Clipboard, exportWriter = writeConversationExport, permissionRuleStore, sandboxStore: suppliedSandboxStore, recentlyDeniedStore: suppliedRecentlyDeniedStore, terminalSetup: terminalSetupOverride, themeStore, initialThemeSettings, initialThemeLoadError, workspaceDirectoryResolver = resolveTuiWorkspaceDirectory, workspaceDirectoryCompleter = completeTuiWorkspaceDirectory, runtimeSettings: suppliedRuntimeSettings, runtimeSettingsTarget, notificationWriter, elicitationUrlOpener = openTuiUrl, releaseNotesLoader = (configRoot) => loadClaudeReleaseNotes({ configRoot }), settingSources, }) {
     const { exit, suspendTerminal, waitUntilRenderFlush } = useApp();
     const width = useTerminalWidth(terminalWidth);
     const keybindingsRoot = useMemo(() => resolve(keybindingsConfigRoot ??
@@ -304,6 +305,7 @@ export function InteractiveApp({ factory, initialSessions, initialPrompt, initia
     const statusLineSessionId = useRef(resume?.sessionId ?? randomUUID());
     const sessionIdRef = useRef(resume?.sessionId ?? null);
     sessionIdRef.current = sessionId;
+    const [sessionColor, setSessionColor] = useState(initialSessionColor);
     const [sessionName, setSessionName] = useState(null);
     const [activeSessionSummary, setActiveSessionSummary] = useState(() => resume?.sessionId
         ? initialSessions.find((session) => session.sessionId === resume.sessionId)
@@ -443,6 +445,17 @@ export function InteractiveApp({ factory, initialSessions, initialPrompt, initia
     const matchingSlashCommands = useMemo(() => commandQuery === null
         ? []
         : filterTuiSlashCommands(allSlashCommands, commandQuery), [allSlashCommands, commandQuery]);
+    const commandArgumentHint = useMemo(() => {
+        if (shellMode || !input.startsWith('/'))
+            return undefined;
+        if (inputCursor !== input.length)
+            return undefined;
+        const match = /^\/(\S+) $/u.exec(input);
+        if (!match?.[1])
+            return undefined;
+        const command = allSlashCommands.find((candidate) => candidate.name === match[1]);
+        return command?.argumentHint;
+    }, [allSlashCommands, input, inputCursor, shellMode]);
     const commandPaletteVisible = !busy &&
         !permission &&
         !planApproval &&
@@ -1443,14 +1456,19 @@ export function InteractiveApp({ factory, initialSessions, initialPrompt, initia
         sessionLoadRef.current = loadId;
         if (nextSessionId === null) {
             setHistory([]);
+            setSessionColor(undefined);
             return;
         }
         const loading = (async () => {
             try {
                 const commands = await service();
                 const transcript = await commands.transcript?.(nextSessionId);
+                const agentColor = commands.agentColor === undefined
+                    ? undefined
+                    : await commands.agentColor(nextSessionId);
                 if (sessionLoadRef.current === loadId) {
                     setHistory(transcript ? [...transcript] : []);
+                    setSessionColor(agentColor);
                 }
             }
             catch (error) {
@@ -1816,6 +1834,32 @@ export function InteractiveApp({ factory, initialSessions, initialPrompt, initia
         onTurnChange?.(showing);
         void showing.finally(() => onTurnChange?.(null));
     };
+    const changeSessionColor = (display, selection) => {
+        appendPromptHistory(display);
+        if (selection.kind === 'color')
+            setSessionColor(selection.color);
+        else if (selection.kind === 'reset')
+            setSessionColor(undefined);
+        const changing = (async () => {
+            try {
+                const activeSessionId = await withLocalCommands(async (commands) => {
+                    if (!commands.recordColorUsage) {
+                        throw new Error('Session color is unavailable.');
+                    }
+                    return commands.recordColorUsage(sessionId ?? undefined, selection, display, runtimePreferencesRef.current.permissionMode);
+                });
+                if (activeSessionId)
+                    setSessionId(activeSessionId);
+                append({ kind: 'user', text: display });
+                append({ kind: 'local-result', text: agentColorMessage(selection) });
+            }
+            catch (error) {
+                warn(error);
+            }
+        })();
+        onTurnChange?.(changing);
+        void changing.finally(() => onTurnChange?.(null));
+    };
     const backgroundSession = () => {
         appendPromptHistory('/background');
         const backgrounding = (async () => {
@@ -4794,6 +4838,7 @@ export function InteractiveApp({ factory, initialSessions, initialPrompt, initia
             if (!prompt || prompt === '!')
                 return;
             const copyCommand = /^\/copy(?:\s+(\d+))?$/u.exec(prompt);
+            const colorCommand = /^\/color(?:\s+([\s\S]+))?$/u.exec(prompt);
             const sandboxCommand = /^\/sandbox(?:\s+([\s\S]+))?$/u.exec(prompt);
             const tuiCommand = /^\/tui(?:\s+(default|fullscreen))?$/u.exec(prompt);
             const renameCommand = /^\/rename(?:\s+(.+))?$/u.exec(prompt);
@@ -4808,12 +4853,14 @@ export function InteractiveApp({ factory, initialSessions, initialPrompt, initia
             else if (prompt === '/new') {
                 statusLineSessionId.current = randomUUID();
                 setSessionId(null);
+                setSessionColor(undefined);
                 setPendingFork(false);
                 append({ kind: 'notice', text: 'Started a new session.' });
             }
             else if (prompt === '/clear') {
                 statusLineSessionId.current = randomUUID();
                 setSessionId(null);
+                setSessionColor(undefined);
                 setPendingFork(false);
                 setHistory([]);
                 setUsage(undefined);
@@ -4951,6 +4998,9 @@ export function InteractiveApp({ factory, initialSessions, initialPrompt, initia
                     text: 'The /agents wizard has been removed.\n\nAsk Claude to create or update subagents for you (e.g. "create a code-reviewer subagent that ..."),\nor edit the files directly:\n  • .claude/agents/       (this project)\n  • ~/.claude/agents/     (all projects)\n\nDocs: https://code.claude.com/docs/en/sub-agents',
                 });
             }
+            else if (colorCommand) {
+                changeSessionColor(prompt, parseAgentColorInput(colorCommand[1] ?? ''));
+            }
             else if (btwCommand) {
                 const sideQuestion = btwCommand[1]?.trim();
                 if (sideQuestion)
@@ -5420,7 +5470,9 @@ export function InteractiveApp({ factory, initialSessions, initialPrompt, initia
                                 label: 'Save to file',
                                 description: 'Save the conversation to a file in the current directory',
                             },
-                        ], selectedIndex: menu.selectedIndex, footer: "Esc to cancel", width: width, screenReader: axScreenReader })) : menu.kind === 'copy' ? (_jsx(SelectionMenu, { title: "Copy", description: "Select content to copy:", options: menu.candidates, selectedIndex: menu.selectedIndex, footer: "Enter to copy \u00B7 w to write to /tmp/claude \u00B7 Esc to cancel", width: width, screenReader: axScreenReader })) : null) : (_jsxs(_Fragment, { children: [commandPaletteVisible ? (_jsx(CommandPalette, { commands: matchingSlashCommands, selectedIndex: selectedSlashCommandIndex, width: width, screenReader: axScreenReader })) : null, filePickerVisible ? (_jsx(MentionPicker, { entries: matchingMentionEntries, selectedIndex: selectedFileIndex, width: width, screenReader: axScreenReader })) : null, exitConfirmation ? (_jsx(Text, { color: activePalette.warning, children: "Press Ctrl-C again to exit" })) : null, _jsx(Composer, { input: shellMode ? input.slice(1) : input, cursor: shellMode ? Math.max(0, inputCursor - 1) : inputCursor, shellMode: shellMode, busy: busy, clipboardBusy: clipboardBusy, status: status, display: runtimeDisplay, ...(usage === undefined ? {} : { usage }), ...(costUsd === undefined ? {} : { costUsd }), width: width, screenReader: axScreenReader, hasThinking: hasDetailedTranscript, thinkingExpanded: thinkingExpanded, reduceMotion: runtimeSettings.reduceMotion, progressBar: runtimeSettings.progressBar, ...(runtimeSettings.turnDuration
+                        ], selectedIndex: menu.selectedIndex, footer: "Esc to cancel", width: width, screenReader: axScreenReader })) : menu.kind === 'copy' ? (_jsx(SelectionMenu, { title: "Copy", description: "Select content to copy:", options: menu.candidates, selectedIndex: menu.selectedIndex, footer: "Enter to copy \u00B7 w to write to /tmp/claude \u00B7 Esc to cancel", width: width, screenReader: axScreenReader })) : null) : (_jsxs(_Fragment, { children: [commandPaletteVisible ? (_jsx(CommandPalette, { commands: matchingSlashCommands, selectedIndex: selectedSlashCommandIndex, width: width, screenReader: axScreenReader })) : null, filePickerVisible ? (_jsx(MentionPicker, { entries: matchingMentionEntries, selectedIndex: selectedFileIndex, width: width, screenReader: axScreenReader })) : null, exitConfirmation ? (_jsx(Text, { color: activePalette.warning, children: "Press Ctrl-C again to exit" })) : null, _jsx(Composer, { input: shellMode ? input.slice(1) : input, cursor: shellMode ? Math.max(0, inputCursor - 1) : inputCursor, shellMode: shellMode, ...(sessionColor === undefined ? {} : { sessionColor }), ...(commandArgumentHint === undefined
+                                    ? {}
+                                    : { commandArgumentHint }), busy: busy, clipboardBusy: clipboardBusy, status: status, display: runtimeDisplay, ...(usage === undefined ? {} : { usage }), ...(costUsd === undefined ? {} : { costUsd }), width: width, screenReader: axScreenReader, hasThinking: hasDetailedTranscript, thinkingExpanded: thinkingExpanded, reduceMotion: runtimeSettings.reduceMotion, progressBar: runtimeSettings.progressBar, ...(runtimeSettings.turnDuration
                                     ? (() => {
                                         const duration = formatTurnDuration(turnDuration);
                                         return duration === undefined
@@ -5534,11 +5586,16 @@ export async function runInteractive(options) {
             initialAgentPromptResolved = true;
         }
         let initialHistory = [];
+        let initialSessionColor;
         try {
             initialHistory =
                 resume?.sessionId === undefined || listing.transcript === undefined
                     ? []
                     : await listing.transcript(resume.sessionId);
+            initialSessionColor =
+                resume?.sessionId === undefined || listing.agentColor === undefined
+                    ? undefined
+                    : await listing.agentColor(resume.sessionId);
         }
         catch (error) {
             try {
@@ -5563,7 +5620,7 @@ export async function runInteractive(options) {
         let cleanup = null;
         let backgrounded;
         rendererChange = null;
-        const instance = render(_jsx(InteractiveApp, { factory: options.factory, initialSessions: initialSessions, slashCommands: initialSlashCommands, agents: initialAgents, initialHistory: history, runtimeSettings: currentRuntimeSettings, ...(options.settingSources === undefined
+        const instance = render(_jsx(InteractiveApp, { factory: options.factory, initialSessions: initialSessions, slashCommands: initialSlashCommands, agents: initialAgents, initialHistory: history, ...(initialSessionColor === undefined ? {} : { initialSessionColor }), runtimeSettings: currentRuntimeSettings, ...(options.settingSources === undefined
                 ? {}
                 : { settingSources: options.settingSources }), initialThemeSettings: initialThemeSettings, ...(initialThemeLoadError === undefined
                 ? {}

package/dist/cli/protocol.d.ts

@@ -206,6 +206,13 @@ export interface ProtocolResult {
 }
 export declare function createSuccessResult(result: ProtocolResult, info: CliRuntimeInfo, startedAt: number, modelTurns: number): Record<string, unknown>;
 export declare function createErrorResult(message: string, sessionId: string, startedAt: number, modelTurns: number): Record<string, unknown>;
+/**
+ * Returns the argument text of a headless `/color` prompt, or undefined when
+ * the prompt is not a bare `/color` command. A trailing space matches with an
+ * empty argument (random color), while `/colorblue` and `/colorful` are not
+ * the command.
+ */
+export declare function matchHeadlessColorCommand(prompt: string): string | undefined;
 export declare function parseCliInvocation(argv: readonly string[]): CliInvocation;
 export declare function readStreamJsonMessages(input: AsyncIterable<string | Uint8Array>): AsyncGenerator<StreamJsonMessage>;
 export declare function readStreamUserMessages(input: AsyncIterable<string | Uint8Array>): AsyncGenerator<StreamUserMessage>;
@@ -232,6 +239,12 @@ export declare class StreamJsonOutput {
     constructor(write: (value: unknown) => void, info: CliRuntimeInfo, sessionId: string, includePartialMessages: boolean, includeHookEvents?: boolean);
     init(): void;
     replayUser(message: StreamUserMessage['message']): void;
+    /**
+     * Emits the synthetic assistant message for a provider-free local command
+     * (e.g. /color). It must not touch the turn state, so the following result
+     * keeps num_turns 0 and no stream_event records are produced.
+     */
+    syntheticAssistant(text: string): void;
     controlRequest(request: {
         request_id: string;
         request: Record<string, unknown>;

package/dist/cli/protocol.js

@@ -80,6 +80,18 @@ export function createErrorResult(message, sessionId, startedAt, modelTurns) {
         uuid: randomUUID(),
     };
 }
+/**
+ * Returns the argument text of a headless `/color` prompt, or undefined when
+ * the prompt is not a bare `/color` command. A trailing space matches with an
+ * empty argument (random color), while `/colorblue` and `/colorful` are not
+ * the command.
+ */
+export function matchHeadlessColorCommand(prompt) {
+    const match = /^\/color(?:\s+([\s\S]*))?$/u.exec(prompt);
+    if (match === null)
+        return undefined;
+    return match[1] ?? '';
+}
 const INPUT_FORMATS = ['text', 'stream-json'];
 const OUTPUT_FORMATS = ['text', 'json', 'stream-json'];
 const PERMISSION_MODES = [
@@ -1594,6 +1606,28 @@ export class StreamJsonOutput {
     replayUser(message) {
         this.write({ type: 'user', message, session_id: this.sessionId });
     }
+    /**
+     * Emits the synthetic assistant message for a provider-free local command
+     * (e.g. /color). It must not touch the turn state, so the following result
+     * keeps num_turns 0 and no stream_event records are produced.
+     */
+    syntheticAssistant(text) {
+        this.write({
+            type: 'assistant',
+            message: {
+                id: randomUUID(),
+                type: 'message',
+                role: 'assistant',
+                model: '<synthetic>',
+                content: [{ type: 'text', text }],
+                stop_reason: 'stop_sequence',
+                stop_sequence: '',
+                usage: { input_tokens: 0, output_tokens: 0 },
+            },
+            parent_tool_use_id: null,
+            session_id: this.sessionId,
+        });
+    }
     controlRequest(request) {
         this.write({ type: 'control_request', ...request });
     }

package/dist/cli/tui/claude-command-inventory.d.ts

@@ -38,9 +38,8 @@ export declare const CLAUDE_2_1_208_COMMAND_INVENTORY: readonly [{
     readonly visibility: "visible";
 }, {
     readonly name: "color";
-    readonly disposition: "deferred";
+    readonly disposition: "included";
     readonly visibility: "visible";
-    readonly reason: "The dedicated /color contract is required; /theme is not a substitute.";
 }, {
     readonly name: "compact";
     readonly disposition: "included";

package/dist/cli/tui/claude-command-inventory.js

@@ -20,12 +20,7 @@ export const CLAUDE_2_1_208_COMMAND_INVENTORY = [
         reason: 'The CLI-driven Chrome integration is required parity work and is not implemented yet.',
     },
     { name: 'clear', disposition: 'included', visibility: 'visible' },
-    {
-        name: 'color',
-        disposition: 'deferred',
-        visibility: 'visible',
-        reason: 'The dedicated /color contract is required; /theme is not a substitute.',
-    },
+    { name: 'color', disposition: 'included', visibility: 'visible' },
     { name: 'compact', disposition: 'included', visibility: 'visible' },
     { name: 'config', disposition: 'included', visibility: 'visible' },
     { name: 'copy', disposition: 'included', visibility: 'visible' },

package/dist/cli/tui/claude-style.d.ts

@@ -1,4 +1,5 @@
 import type { ModelToolCall, ModelUsage } from '../../core/runtime.js';
+import type { AgentColorName } from '../../compatibility/claude/agent-color.js';
 import type { TuiFileEntry, TuiMentionEntry } from './file-picker.js';
 import { type TuiDiffSnapshot } from './git-diff.js';
 import { type TuiHookConfiguration } from './hook-settings.js';
@@ -230,7 +231,7 @@ export declare function ModelMenu({ options, effort, selectedIndex, width, scree
 export declare function ExternalEditorWait({ screenReader, }: {
     screenReader: boolean;
 }): import("react").JSX.Element;
-export declare function Composer({ input, cursor, busy, clipboardBusy, status, display, usage, costUsd, width, screenReader, hasThinking, thinkingExpanded, shortcutsVisible, shellMode, footerMessage, reduceMotion, progressBar, turnDuration, editorMode, prStatus, }: {
+export declare function Composer({ input, cursor, busy, clipboardBusy, status, display, usage, costUsd, width, screenReader, hasThinking, thinkingExpanded, shortcutsVisible, shellMode, footerMessage, reduceMotion, progressBar, turnDuration, editorMode, prStatus, sessionColor, commandArgumentHint, }: {
     input: string;
     cursor?: number;
     busy: boolean;
@@ -254,6 +255,8 @@ export declare function Composer({ input, cursor, busy, clipboardBusy, status, d
     turnDuration?: string;
     editorMode?: 'normal' | 'vim';
     prStatus?: string;
+    sessionColor?: AgentColorName;
+    commandArgumentHint?: string;
 }): import("react").JSX.Element;
 export declare function DialogFrame({ title, children, screenReader, }: {
     title: string;

package/dist/cli/tui/claude-style.js

@@ -659,7 +659,7 @@ export function ExternalEditorWait({ screenReader, }) {
         return _jsx(Text, { children: "External editor open. Save and close it to continue." });
     return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500" }), _jsx(Text, { children: "Save and close editor to continue..." }), _jsx(Text, { dimColor: true, children: "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500" })] }));
 }
-export function Composer({ input, cursor, busy, clipboardBusy = false, status, display, usage, costUsd, width, screenReader, hasThinking = false, thinkingExpanded = false, shortcutsVisible = false, shellMode = false, footerMessage, reduceMotion = false, progressBar = true, turnDuration, editorMode = 'normal', prStatus, }) {
+export function Composer({ input, cursor, busy, clipboardBusy = false, status, display, usage, costUsd, width, screenReader, hasThinking = false, thinkingExpanded = false, shortcutsVisible = false, shellMode = false, footerMessage, reduceMotion = false, progressBar = true, turnDuration, editorMode = 'normal', prStatus, sessionColor, commandArgumentHint, }) {
     const palette = useTuiPalette();
     const [spinnerIndex, setSpinnerIndex] = useState(0);
     useEffect(() => {
@@ -677,15 +677,20 @@ export function Composer({ input, cursor, busy, clipboardBusy = false, status, d
                         ? `Shell command: ${input}`
                         : `Prompt: ${input}` }));
     const line = '─'.repeat(Math.max(12, Math.min(100, width)));
+    const separatorColor = sessionColor === undefined ? undefined : palette.sessionColors[sessionColor];
     return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [usage ? (_jsxs(Text, { dimColor: true, children: ["Context \u00B7 ", usage.inputTokens + usage.outputTokens, " tokens", display.contextWindowTokens
                         ? ` / ${display.contextWindowTokens} (${Math.min(100, Math.round(((usage.inputTokens + usage.outputTokens) /
                             display.contextWindowTokens) *
                             100))}%)`
                         : '', usage.cacheReadInputTokens
                         ? ` · ${usage.cacheReadInputTokens} cached`
-                        : '', costUsd === undefined ? '' : ` · $${costUsd.toFixed(6)}`] })) : null, _jsx(Text, { dimColor: true, children: line }), clipboardBusy ? (_jsx(Text, { children: "Pasting\u2026" })) : busy ? (_jsxs(Text, { children: [progressBar ? (_jsx(Text, { color: palette.accent, children: reduceMotion ? '•' : SPINNER[spinnerIndex] })) : null, ' ', status, "\u2026 ", _jsx(Text, { dimColor: true, children: "\u00B7 esc to interrupt" })] })) : (_jsxs(Text, { children: [_jsx(Text, { ...(shellMode ? {} : { color: palette.brand }), bold: true, children: shellMode ? '! ' : '❯ ' }), input ? (_jsx(ComposerInput, { cursor: cursor ?? Array.from(input).length, input: input })) : (_jsx(Text, { dimColor: true, children: shellMode
+                        : '', costUsd === undefined ? '' : ` · $${costUsd.toFixed(6)}`] })) : null, _jsx(Text, { ...(separatorColor === undefined
+                    ? { dimColor: true }
+                    : { color: separatorColor }), children: line }), clipboardBusy ? (_jsx(Text, { children: "Pasting\u2026" })) : busy ? (_jsxs(Text, { children: [progressBar ? (_jsx(Text, { color: palette.accent, children: reduceMotion ? '•' : SPINNER[spinnerIndex] })) : null, ' ', status, "\u2026 ", _jsx(Text, { dimColor: true, children: "\u00B7 esc to interrupt" })] })) : (_jsxs(Text, { children: [_jsx(Text, { ...(shellMode ? {} : { color: palette.brand }), bold: true, children: shellMode ? '! ' : '❯ ' }), input ? (_jsxs(Text, { children: [_jsx(ComposerInput, { cursor: cursor ?? Array.from(input).length, input: input }), commandArgumentHint ? (_jsxs(Text, { dimColor: true, children: [input.endsWith(' ') ? '' : ' ', commandArgumentHint] })) : null] })) : (_jsx(Text, { dimColor: true, children: shellMode
                             ? 'Enter a shell command'
-                            : 'Try "review this project"' }))] })), _jsx(Text, { dimColor: true, children: line }), shortcutsVisible ? (_jsx(ShortcutHelp, { width: width })) : (_jsxs(Box, { width: Math.min(100, width), children: [_jsx(Text, { dimColor: true, children: shellMode ? ('! for bash mode') : (_jsxs(_Fragment, { children: ["\u23F5\u23F5 ", permissionLabel(display.permissionMode), " \u00B7", ' ', busy ? 'esc to interrupt' : '? for shortcuts', " \u00B7 \u2190 for agents", hasThinking
+                            : 'Try "review this project"' }))] })), _jsx(Text, { ...(separatorColor === undefined
+                    ? { dimColor: true }
+                    : { color: separatorColor }), children: line }), shortcutsVisible ? (_jsx(ShortcutHelp, { width: width })) : (_jsxs(Box, { width: Math.min(100, width), children: [_jsx(Text, { dimColor: true, children: shellMode ? ('! for bash mode') : (_jsxs(_Fragment, { children: ["\u23F5\u23F5 ", permissionLabel(display.permissionMode), " \u00B7", ' ', busy ? 'esc to interrupt' : '? for shortcuts', " \u00B7 \u2190 for agents", hasThinking
                                     ? ` · ctrl+o ${thinkingExpanded ? 'collapse' : 'expand'}`
                                     : ''] })) }), _jsx(Box, { flexGrow: 1 }), footerMessage ? (footerMessage.isError ? (_jsx(Text, { color: palette.error, children: footerMessage.text })) : (_jsx(Text, { dimColor: true, children: footerMessage.text }))) : prStatus ? (_jsx(Text, { dimColor: true, children: prStatus })) : turnDuration ? (_jsxs(Text, { dimColor: true, children: ["Cooked for ", turnDuration] })) : display.effort ? (_jsxs(Text, { children: [_jsxs(Text, { color: palette.accent, children: ["\u25CF ", display.effort] }), _jsxs(Text, { dimColor: true, children: [' ', "\u00B7 ", editorMode === 'vim' ? 'vim' : '/effort'] })] })) : null] }))] }));
 }

package/dist/cli/tui/slash-commands.d.ts

@@ -3,6 +3,7 @@ export interface TuiSlashCommand {
     name: string;
     description: string;
     source: TuiSlashCommandSource;
+    argumentHint?: string;
     progressMessage?: string;
 }
 export declare const BUILTIN_TUI_SLASH_COMMANDS: readonly TuiSlashCommand[];

package/dist/cli/tui/slash-commands.js

@@ -34,6 +34,12 @@ export const BUILTIN_TUI_SLASH_COMMANDS = [
         description: 'Start a new session with empty context; previous session stays on disk (resumable with /resume)',
         source: 'builtin',
     },
+    {
+        name: 'color',
+        description: 'Set the prompt bar color for this session',
+        argumentHint: '[red|blue|green|yellow|purple|orange|pink|cyan|default]',
+        source: 'builtin',
+    },
     {
         name: 'compact',
         description: 'Clear conversation history but keep a summary in context',

package/dist/cli/tui/theme.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from 'react';
+import type { AgentColorName } from '../../compatibility/claude/agent-color.js';
 import type { TuiCustomTheme } from './custom-themes.js';
 export declare const TUI_THEMES: readonly ["auto", "dark", "light", "dark-daltonized", "light-daltonized", "dark-ansi", "light-ansi"];
 export type TuiTheme = (typeof TUI_THEMES)[number];
@@ -31,6 +32,7 @@ export interface TuiPalette {
     warning: string;
     muted: string;
     selectionText: string;
+    sessionColors: Readonly<Record<AgentColorName, string>>;
     syntaxTheme: 'Monokai Extended' | 'GitHub' | 'ansi';
     syntax: TuiSyntaxPalette;
 }

package/dist/cli/tui/theme.js

@@ -44,6 +44,56 @@ const LIGHT_SYNTAX = {
     addedBackground: '#d7ffd7',
     addedHighlight: '#afffaf',
 };
+const NORMAL_SESSION_COLORS = {
+    red: '#dc2626',
+    blue: '#2563eb',
+    green: '#16a34a',
+    yellow: '#ca8a04',
+    purple: '#9333ea',
+    orange: '#ea580c',
+    pink: '#db2777',
+    cyan: '#0891b2',
+};
+const LIGHT_ANSI_SESSION_COLORS = {
+    red: 'red',
+    blue: 'blue',
+    green: 'green',
+    yellow: 'yellow',
+    purple: 'magenta',
+    orange: 'redBright',
+    pink: 'magentaBright',
+    cyan: 'cyan',
+};
+const DARK_ANSI_SESSION_COLORS = {
+    red: 'redBright',
+    blue: 'blueBright',
+    green: 'greenBright',
+    yellow: 'yellowBright',
+    purple: 'magentaBright',
+    orange: 'redBright',
+    pink: 'magentaBright',
+    cyan: 'cyanBright',
+};
+const LIGHT_DALTONIZED_SESSION_COLORS = {
+    red: '#cc0000',
+    blue: '#0066cc',
+    green: '#00cc00',
+    yellow: '#ffcc00',
+    purple: '#800080',
+    orange: '#ff8000',
+    pink: '#ff66b2',
+    cyan: '#00b2b2',
+};
+const DARK_DALTONIZED_SESSION_COLORS = {
+    red: '#ff6666',
+    blue: '#66b2ff',
+    green: '#66ff66',
+    yellow: '#ffff66',
+    purple: '#b266ff',
+    orange: '#ffb266',
+    pink: '#ff99cc',
+    cyan: '#66cccc',
+};
 function automaticDark(environment) {
     const background = environment.COLORFGBG?.split(';').at(-1);
     return background === undefined || Number(background) < 8;
@@ -195,11 +245,30 @@ export function tuiPalette(profile, syntaxHighlightingDisabled = false, environm
         ? adaptSyntaxColors(syntaxBase, adaptAutoColor)
         : syntaxBase;
     const autoColor = (color) => profile === 'auto' ? adaptAutoColor(color) : color;
+    const sessionColors = ansiOnly
+        ? dark
+            ? DARK_ANSI_SESSION_COLORS
+            : LIGHT_ANSI_SESSION_COLORS
+        : daltonized
+            ? dark
+                ? DARK_DALTONIZED_SESSION_COLORS
+                : LIGHT_DALTONIZED_SESSION_COLORS
+            : {
+                red: autoColor(NORMAL_SESSION_COLORS.red),
+                blue: autoColor(NORMAL_SESSION_COLORS.blue),
+                green: autoColor(NORMAL_SESSION_COLORS.green),
+                yellow: autoColor(NORMAL_SESSION_COLORS.yellow),
+                purple: autoColor(NORMAL_SESSION_COLORS.purple),
+                orange: autoColor(NORMAL_SESSION_COLORS.orange),
+                pink: autoColor(NORMAL_SESSION_COLORS.pink),
+                cyan: autoColor(NORMAL_SESSION_COLORS.cyan),
+            };
     const palette = {
         profile,
         dark,
         ansiOnly,
         syntaxHighlightingDisabled,
+        sessionColors,
         brand: ansiOnly ? 'redBright' : autoColor('#D97757'),
         accent: ansiOnly
             ? 'magentaBright'

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { type ForkResult, type ManualCompactResult, type ManualCompactSelection, type RewindPoint, type SessionForkCheckpoint, type SessionInspection, type SessionRunResult, type SessionSummary, type SideQuestionForkResult, type SideQuestionResult } from './application/session-service.js';
+import { type AgentColorName, type AgentColorSelection } from './compatibility/claude/agent-color.js';
 import type { ClaudeDisplayTranscriptItem } from './compatibility/claude/projection.js';
 import { type ModelDocument, type ModelImage, type ModelProvider, type ModelToolCall, type PermissionApproval, type PermissionDecision, type ToolRegistry, type RuntimeEventSink } from './core/runtime.js';
 import type { InteractiveResumeOptions, InteractiveServiceFactory } from './cli/interactive.js';
@@ -40,6 +41,10 @@ interface SessionCommands {
     retryRecentlyDenied?(sessionId: string, display: string, signal?: AbortSignal): Promise<SessionRunResult>;
     answerSideQuestion?(sessionId: string | undefined, question: string, signal?: AbortSignal, onDelta?: (delta: string) => void, permissionMode?: ClaudePermissionMode): Promise<SideQuestionResult>;
     recordBtwUsage?(sessionId: string | undefined, permissionMode?: ClaudePermissionMode): Promise<string>;
+    recordColorUsage?(sessionId: string | undefined, selection: AgentColorSelection, display: string, permissionMode?: ClaudePermissionMode, options?: {
+        createSession?: boolean;
+    }): Promise<string>;
+    agentColor?(sessionId: string): Promise<AgentColorName | undefined>;
     recordBackgroundUsage?(sessionId: string | undefined, permissionMode?: ClaudePermissionMode): Promise<string>;
     recordBackgroundLaunch?(sessionId: string): Promise<SessionForkCheckpoint>;
     forkSideQuestion?(sessionId: string, question: string, signal?: AbortSignal): Promise<SideQuestionForkResult>;

package/dist/cli.js

@@ -7,6 +7,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { randomUUID } from 'node:crypto';
 import { ClaudeSessionService, } from './application/session-service.js';
+import { agentColorMessage, parseAgentColorInput, } from './compatibility/claude/agent-color.js';
 import { ClaudeConditionalRuleResolver, ClaudeContextAssembler, } from './compatibility/claude/context.js';
 import { loadClaudeDynamicContext } from './compatibility/claude/dynamic-context.js';
 import { createClaudePrSessionFilter, filterClaudePrLinkedSessions, } from './compatibility/claude/pr-links.js';
@@ -46,7 +47,7 @@ import { WorkspaceContext } from './application/session-worktree.js';
 import { launchTmuxWorktree } from './platform/tmux-worktree.js';
 import { claudeSandboxRuntime } from './sandbox/claude-sandbox-runtime.js';
 import { claudeSandboxTempDirectory, loadClaudeSandboxSettings, } from './sandbox/claude-sandbox-settings.js';
-import { createErrorResult, createSuccessResult, parseCliInvocation, readStreamJsonMessages, StreamJsonOutput, } from './cli/protocol.js';
+import { createErrorResult, createSuccessResult, matchHeadlessColorCommand, parseCliInvocation, readStreamJsonMessages, StreamJsonOutput, } from './cli/protocol.js';
 import { describeClaudePlugin, initClaudePlugin, installClaudePlugin, loadClaudePlugins, readPluginRegistry, setClaudePluginEnabled, uninstallClaudePlugin, updateClaudePlugin, validateClaudePlugin, } from './plugins/claude-plugin-runtime.js';
 import { addClaudeMarketplace, disableAllNativePlugins, installClaudeMarketplacePlugin, listClaudeMarketplaceAvailablePlugins, listNativePluginRecords, readClaudeKnownMarketplaces, removeClaudeMarketplace, setNativePluginEnabled, saveClaudePluginConfig, uninstallNativePlugin, updateClaudeMarketplace, updateNativePlugin, validateClaudeMarketplace, } from './plugins/claude-plugin-marketplace.js';
 import { executeClaudePluginEvalCommand, PLUGIN_EVAL_HELP, } from './plugins/claude-plugin-eval.js';
@@ -1343,6 +1344,8 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             retryRecentlyDenied: (sessionId, display, retrySignal) => service.retryRecentlyDenied(sessionId, display, retrySignal),
             answerSideQuestion: (sessionId, question, sideSignal, onDelta, permissionMode) => service.answerSideQuestion(sessionId, question, sideSignal, onDelta, permissionMode),
             recordBtwUsage: (sessionId, permissionMode) => service.recordBtwUsage(sessionId, permissionMode),
+            recordColorUsage: (sessionId, selection, display, permissionMode, options) => service.recordColorUsage(sessionId, selection, display, permissionMode, options),
+            agentColor: (sessionId) => service.readEffectiveAgentColor(sessionId),
             recordBackgroundUsage: (sessionId, permissionMode) => service.recordBackgroundUsage(sessionId, permissionMode),
             recordBackgroundLaunch: (sessionId) => service.recordBackgroundLaunch(sessionId),
             forkSideQuestion: (sessionId, question, sideSignal) => service.forkSideQuestion(sessionId, question, sideSignal),
@@ -3735,6 +3738,7 @@ async function execute(argv, io, dependencies, signal) {
     const pendingEvents = [];
     let streamIterator;
     let firstStreamMessage;
+    let streamInputExhausted = false;
     const queuedStreamUsers = [];
     const earlyControlResponses = new Map();
     let currentTurnAbort;
@@ -3934,6 +3938,19 @@ async function execute(argv, io, dependencies, signal) {
         }
         return 0;
     }
+    const headlessTurnReached = invocation.rewindFiles === undefined &&
+        !['sessions', 'fork', 'inspect', 'export'].includes(command ?? 'run');
+    if (streamIterator && headlessTurnReached) {
+        const first = await nextStreamUser();
+        if (first)
+            firstStreamMessage = first;
+        else
+            streamInputExhausted = true;
+    }
+    const firstHeadlessPrompt = firstStreamMessage?.prompt ?? headlessPrompt;
+    const firstTurnIsLocalColor = !invocation.disableSlashCommands &&
+        firstHeadlessPrompt !== undefined &&
+        matchHeadlessColorCommand(firstHeadlessPrompt) !== undefined;
     const service = await dependencies.createService({
         eventSink: outputFormat === 'stream-json' && !invocation.legacyJson
             ? (event) => {
@@ -3958,8 +3975,7 @@ async function execute(argv, io, dependencies, signal) {
                     }
                 }
                 : eventSink(io, outputFormat, invocation.legacyJson),
-        requireProvider: invocation.rewindFiles === undefined &&
-            !['fork', 'sessions', 'inspect', 'export'].includes(command ?? 'run'),
+        requireProvider: !streamInputExhausted && !firstTurnIsLocalColor && headlessTurnReached,
         ...(retryInterruptedTools ? { approveRecovery: () => true } : {}),
         ...(streamIterator ? { approveTool: approveStreamTool } : {}),
         ...(streamIterator ? { onElicitation: respondStreamElicitation } : {}),
@@ -4067,12 +4083,8 @@ async function execute(argv, io, dependencies, signal) {
         if (outputFormat === 'stream-json' && !invocation.legacyJson) {
             streamOutput = new StreamJsonOutput((value) => writeJson(io, value), runtimeInfo, activeSessionId, includePartialMessages, invocation.includeHookEvents);
         }
-        if (streamIterator) {
-            const first = await nextStreamUser();
-            if (!first)
-                return 0;
-            firstStreamMessage = first;
-        }
+        if (streamInputExhausted)
+            return 0;
         const initialPrompt = firstStreamMessage?.prompt ??
             promptFrom(command === 'resume'
                 ? args.slice(2)
@@ -4099,15 +4111,38 @@ async function execute(argv, io, dependencies, signal) {
                     streamOutput.replayUser(streamMessage.message);
             }
             let result;
+            let colorArgs;
             try {
-                result =
-                    existingSessionId !== undefined || !isFirstTurn
-                        ? runSignal
-                            ? await service.resume(activeSessionId, prompt, runSignal, undefined, streamMessage?.images, streamMessage?.documents)
-                            : await service.resume(activeSessionId, prompt, undefined, undefined, streamMessage?.images, streamMessage?.documents)
-                        : runSignal
-                            ? await service.run(prompt, runSignal, activeSessionId, undefined, streamMessage?.images, streamMessage?.documents)
-                            : await service.run(prompt, undefined, activeSessionId, undefined, streamMessage?.images, streamMessage?.documents);
+                colorArgs = invocation.disableSlashCommands
+                    ? undefined
+                    : matchHeadlessColorCommand(prompt);
+                if (colorArgs !== undefined) {
+                    if (!service.recordColorUsage) {
+                        throw new Error('Session color is unavailable.');
+                    }
+                    const selection = parseAgentColorInput(colorArgs);
+                    const localSessionId = await service.recordColorUsage(activeSessionId, selection, prompt, invocation.permissionMode, isFirstTurn && existingSessionId === undefined
+                        ? { createSession: true }
+                        : undefined);
+                    result = {
+                        sessionId: localSessionId,
+                        text: agentColorMessage(selection),
+                        usage: { inputTokens: 0, outputTokens: 0 },
+                        durationApiMs: 0,
+                        costUsd: 0,
+                        modelUsage: {},
+                    };
+                }
+                else {
+                    result =
+                        existingSessionId !== undefined || !isFirstTurn
+                            ? runSignal
+                                ? await service.resume(activeSessionId, prompt, runSignal, undefined, streamMessage?.images, streamMessage?.documents)
+                                : await service.resume(activeSessionId, prompt, undefined, undefined, streamMessage?.images, streamMessage?.documents)
+                            : runSignal
+                                ? await service.run(prompt, runSignal, activeSessionId, undefined, streamMessage?.images, streamMessage?.documents)
+                                : await service.run(prompt, undefined, activeSessionId, undefined, streamMessage?.images, streamMessage?.documents);
+                }
             }
             catch (error) {
                 if (isCancellation(error, turnAbort.signal)) {
@@ -4134,16 +4169,20 @@ async function execute(argv, io, dependencies, signal) {
                 return false;
             }
             activeSessionId = result.sessionId;
-            if (streamOutput)
+            if (streamOutput) {
+                if (colorArgs !== undefined) {
+                    streamOutput.syntheticAssistant(result.text);
+                }
                 streamOutput.result(result, startedAt);
+            }
             else if (outputFormat === 'json') {
                 const resultRuntimeInfo = service.runtimeInfo?.() ?? runtimeInfo;
-                writeJson(io, createSuccessResult(result, resultRuntimeInfo, startedAt, Math.max(1, jsonModelTurns)));
+                writeJson(io, createSuccessResult(result, resultRuntimeInfo, startedAt, colorArgs !== undefined ? 0 : Math.max(1, jsonModelTurns)));
             }
             else if (outputFormat !== 'text')
                 writeJson(io, { type: 'result', ...result });
             else
-                io.stdout('\n');
+                io.stdout(colorArgs !== undefined ? `${result.text}\n` : '\n');
             if (streamOutput && invocation.promptSuggestions) {
                 try {
                     const suggestion = await service.promptSuggestion?.(activeSessionId, runSignal);

package/dist/compatibility/claude/agent-color.d.ts

@@ -0,0 +1,25 @@
+import type { ClaudeTranscriptEntry } from './schema.js';
+export declare const AGENT_COLORS: readonly ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"];
+export type AgentColorName = (typeof AGENT_COLORS)[number];
+export declare const AGENT_COLOR_DEFAULT: "default";
+export type AgentColorValue = AgentColorName | typeof AGENT_COLOR_DEFAULT;
+export declare const AGENT_COLOR_VALUES: readonly AgentColorValue[];
+export declare const AGENT_COLOR_CHOICES: string;
+export declare const RESET_AGENT_COLOR_ALIASES: readonly ["default", "reset", "none", "gray", "grey"];
+export declare function isAgentColorName(value: unknown): value is AgentColorName;
+export declare function isAgentColorValue(value: unknown): value is AgentColorValue;
+export declare function normalizeAgentColorInput(input: string): string;
+export type AgentColorSelection = {
+    kind: 'color';
+    color: AgentColorName;
+} | {
+    kind: 'reset';
+} | {
+    kind: 'invalid';
+    input: string;
+};
+export declare function parseAgentColorInput(input: string): AgentColorSelection;
+export declare function randomAgentColor(): AgentColorName;
+export declare function agentColorMessage(selection: AgentColorSelection): string;
+export declare function getClaudeEffectiveAgentColor(entries: readonly ClaudeTranscriptEntry[], sessionId: string): AgentColorName | undefined;
+//# sourceMappingURL=agent-color.d.ts.map

package/dist/compatibility/claude/agent-color.js

@@ -0,0 +1,79 @@
+export const AGENT_COLORS = [
+    'red',
+    'blue',
+    'green',
+    'yellow',
+    'purple',
+    'orange',
+    'pink',
+    'cyan',
+];
+export const AGENT_COLOR_DEFAULT = 'default';
+export const AGENT_COLOR_VALUES = [
+    ...AGENT_COLORS,
+    AGENT_COLOR_DEFAULT,
+];
+export const AGENT_COLOR_CHOICES = `${AGENT_COLORS.join(', ')}, ${AGENT_COLOR_DEFAULT}`;
+export const RESET_AGENT_COLOR_ALIASES = [
+    AGENT_COLOR_DEFAULT,
+    'reset',
+    'none',
+    'gray',
+    'grey',
+];
+export function isAgentColorName(value) {
+    return (typeof value === 'string' &&
+        AGENT_COLORS.includes(value));
+}
+export function isAgentColorValue(value) {
+    return (typeof value === 'string' &&
+        AGENT_COLOR_VALUES.includes(value));
+}
+export function normalizeAgentColorInput(input) {
+    return input.trim().toLowerCase();
+}
+export function parseAgentColorInput(input) {
+    const normalized = normalizeAgentColorInput(input);
+    if (normalized === '') {
+        return { kind: 'color', color: randomAgentColor() };
+    }
+    if (RESET_AGENT_COLOR_ALIASES.includes(normalized)) {
+        return { kind: 'reset' };
+    }
+    if (isAgentColorName(normalized)) {
+        return { kind: 'color', color: normalized };
+    }
+    return { kind: 'invalid', input: normalized };
+}
+export function randomAgentColor() {
+    const index = Math.floor(Math.random() * AGENT_COLORS.length);
+    const color = AGENT_COLORS[index];
+    if (color === undefined)
+        throw new Error('AGENT_COLORS must not be empty');
+    return color;
+}
+export function agentColorMessage(selection) {
+    switch (selection.kind) {
+        case 'color':
+            return `Session color set to: ${selection.color}`;
+        case 'reset':
+            return 'Session color reset to default';
+        case 'invalid':
+            return `Invalid color "${selection.input}". Available colors: ${AGENT_COLOR_CHOICES}`;
+    }
+}
+export function getClaudeEffectiveAgentColor(entries, sessionId) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry?.type !== 'agent-color' || entry.sessionId !== sessionId) {
+            continue;
+        }
+        const color = entry.agentColor;
+        if (color === AGENT_COLOR_DEFAULT)
+            return undefined;
+        if (isAgentColorName(color))
+            return color;
+    }
+    return undefined;
+}
+//# sourceMappingURL=agent-color.js.map

package/dist/compatibility/claude/fork.js

@@ -152,6 +152,7 @@ function validateNativeHistory(entries) {
     return undefined;
 }
 export function createClaudeNativeFork({ source, sourceSessionId, sessionId, resumeSessionAt, }) {
+    const agentColors = [];
     const titles = [];
     const modes = [];
     const permissionModes = [];
@@ -204,7 +205,9 @@ export function createClaudeNativeFork({ source, sourceSessionId, sessionId, res
             throw new Error('Claude fork source entry has the wrong sessionId');
         }
         const copied = copyClaudeEntryWithSessionId(entry, sessionId);
-        if (entry.type === 'ai-title')
+        if (entry.type === 'agent-color')
+            agentColors.push(copied);
+        else if (entry.type === 'ai-title')
             titles.push(copied);
         else if (entry.type === 'mode')
             modes.push(copied);
@@ -232,6 +235,7 @@ export function createClaudeNativeFork({ source, sourceSessionId, sessionId, res
         lastPrompt = undefined;
     }
     return [
+        ...agentColors.slice(-1),
         ...titles.slice(-1),
         ...modes.slice(-1),
         ...permissionModes.slice(-1),

package/dist/compatibility/claude/schema.js

@@ -1,5 +1,7 @@
+import { isAgentColorValue } from './agent-color.js';
 const SUPPORTED_VERSION = '2.1.208';
 const APPENDABLE_ENTRY_TYPES = new Set([
+    'agent-color',
     'agent-name',
     'agent-setting',
     'assistant',
@@ -17,6 +19,7 @@ const APPENDABLE_ENTRY_TYPES = new Set([
     'worktree-state',
 ]);
 const FORKABLE_ENTRY_TYPES = new Set([
+    'agent-color',
     'agent-name',
     'agent-setting',
     'ai-title',
@@ -717,6 +720,13 @@ function validateAppendableEntry(entry) {
         }
         return;
     }
+    if (entry.type === 'agent-color') {
+        if (!isAgentColorValue(entry.agentColor) ||
+            !isNonEmptyString(entry.sessionId)) {
+            throw new Error('Claude agent-color entry has invalid metadata');
+        }
+        return;
+    }
     if (entry.type === 'agent-name') {
         if (!isNonEmptyString(entry.agentName) ||
             !isNonEmptyString(entry.sessionId)) {
@@ -868,7 +878,9 @@ function validateSidechainEntry(entry) {
     }
 }
 function validateForkableEntry(entry) {
-    if (entry.type === 'custom-title' || entry.type === 'agent-name') {
+    if (entry.type === 'custom-title' ||
+        entry.type === 'agent-name' ||
+        entry.type === 'agent-color') {
         validateAppendableEntry(entry);
         return;
     }

package/dist/persistence/claude-transcript-store.js

@@ -16,6 +16,7 @@ export class ClaudeTranscriptParseError extends Error {
 }
 const UTF8_DECODER = new TextDecoder('utf-8', { fatal: true });
 const NON_TAIL_ENTRY_TYPES = new Set([
+    'agent-color',
     'agent-name',
     'agent-setting',
     'custom-title',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",
@@ -93,6 +93,7 @@
     "test:subagent-compat": "npm run build && node scripts/verify-subagent-compatibility.mjs",
     "test:background-agent-compat": "npm run build && node scripts/verify-background-agent-compatibility.mjs",
     "test:background-command-compat": "npm run build && node scripts/verify-background-command-compatibility.mjs",
+    "test:color-command-compat": "npm run build && node scripts/verify-color-command-compatibility.mjs",
     "test:task-compat": "npm run build && node scripts/verify-task-compatibility.mjs",
     "test:scheduled-compat": "npm run build && node scripts/verify-scheduled-tools-compatibility.mjs",
     "test:top-level-agent-compat": "npm run build && node scripts/verify-top-level-agent-compatibility.mjs",